wiki:IncludeMacro

Version 30 (modified by Cinc-th, 6 months ago) (diff)

Added README information because Include(source:includemacro/trunk/README) doesn't work on this page. The plugin seems to be partly broken.

Include external resources in a wiki page

The following documentation is for the latest development 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)]]

Tip

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

See also: IncludePagesPlugin

Bugs/Feature Requests

Existing bugs and feature requests for IncludeMacro are here.

If you have any issues, create a new ticket.

defect

25 / 33

enhancement

21 / 32

task

2 / 3

Download

Download the zipped source from here.

The macro is also available on PyPi.

Source

Get the appropriate version for your Trac installation:

Final version for Trac 0.10 1.1.0 Browse the source or checkout from here using Subversion
Latest stable for Trac 0.11 2.1.0 Browse the source or checkout from here using Subversion
Latest stable for Trac 1.0+ 3.2.0 Browse the source or checkout from here using Subversion

Installation

General instructions on installing Trac plugins can be found on the 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

18147 by Cinc-th on 2021-04-04 12:26:27
IncludeMacro: fixes for Python 3 support. The macro now works with Trac 1.5/Trac 1.6.
18132 by rjollos on 2021-04-01 19:57:18
TracIncludeMacro 3.3.0dev: Fix ReST formatting
17876 by rjollos on 2020-11-23 23:12:11
TracIncludeMacro 3.2.0: Tag 3.2.0

Refs #13911.

(more)

Author/Contributors

Author: coderanger
Maintainer: Ryan J Ollos
Contributors: hasienda