[[PageOutline(2-5,Contents,pullout)]]

= Include external resources in a wiki page

The following documentation is for the latest development version.

[[Include(source:includemacro/trunk/README)]]

See also: IncludePagesPlugin

== Bugs/Feature Requests

Existing bugs and feature requests for IncludeMacro are 
[report:9?COMPONENT=IncludeMacro here].

If you have any issues, create a 
[/newticket?component=IncludeMacro new ticket].

[[TicketQuery(component=IncludeMacro&group=type,format=progress)]]

== Download

Download the zipped source from [export:includemacro here].

The macro is also available on [pypi:TracIncludeMacro PyPi].

== Source

Get the appropriate version for your Trac installation:

|| Final version for Trac 0.10                   || 1.1.0    || [source:includemacro/tags/1.1.0 Browse the source] or checkout from [/svn/includemacro/tags/1.1.0 here] using Subversion ||
|| Latest stable for Trac 0.11                   || 2.1.0    || [source:includemacro/tags/2.1.0 Browse the source] or checkout from [/svn/includemacro/tags/2.1.0 here] using Subversion ||
|| Latest stable for Trac 1.0+             || 3.2.0 || [source:includemacro/tags/3.2.0 Browse the source] or checkout from [/svn/includemacro/tags/3.2.0 here] using Subversion      ||

== Installation

General instructions on installing Trac plugins can be found on the [TracPlugins#InstallingaTracplugin TracPlugins] page.

== Configuration
From the README of the latest version:
{{{
Notes
=====

This macro lets you include various things.

Currently supported sources:

* HTTP - ``http:`` and ``https:``
* FTP - ``ftp:``
* Wiki pages - ``wiki:``
* Repository files - ``source:``
* Ticket comments - ``ticket:N:comment:M`` (3.0dev, syntax may be changed before release)

The default source is ``wiki`` if only a source path is given.

An optional second argument sets the output MIME type, though in most
cases the default will be correct.

Permissions
===========

The three remote sources (``http``, ``https``, and ``ftp``) require
``INCLUDE_URL`` to be rendered.

Anyone can add a call to these, however they will not be shown. This is
**not** a replacement for ``render_unsafe_content``, see below.

Configuration
=============

If ``[wiki] render_unsafe_content`` is off (the default), any produced
HTML will be sanitized.

.. caution::
    This is a potential security risk! Please review the implications
    ``render_unsafe_content`` before using this feature.

To enable the plugin::

    [components]
    includemacro.* = enabled

Example
=======

Include another wiki page::

    [[Include(PageName)]]

Include a section of a page (the section heading must have an explicit id)::

    [[Include(PageName#section)]]

Include the HEAD revision of a reStructuredText__ file from the repository::

    [[Include(source:trunk/docs/README, text/x-rst)]]

Include a specific revision of a file from the repository::

    [[Include(source:trunk/docs/README@5, text/x-rst)]]

Include only a subpart of file from the repository (use named arguments : start, end, lineno)::

    [[Include(source:trunk/docs/README@5, text/x-rst, start=5, end=15)]]
    [[Include(source:trunk/docs/README@5, text/x-rst, start=5, end=15, lineno=yes)]]

It's possible to use regular expressions in start and/or end parameters

    [[Include(source:trunk/docs/README, start="[a-z]+", end=15, lineno=yes)]]
    [[Include(source:trunk/docs/README, start="[a-z]+", end="\[.+\]", lineno=yes)]]


__ http://docutils.sf.net/rst.html

.. tip::
    If you set the ``svn:mime-type`` property on the file, you can  
    leave off the explicit MIME type.
}}}

== Recent Changes

[[ChangeLog(includemacro, 3)]]

== Author/Contributors

'''Author:''' [wiki:coderanger] [[BR]]
'''Maintainer:''' [[Maintainer]] [[BR]]
'''Contributors:''' hasienda