File inclusion in documents

Starting with version 2.500, Amusewiki can be setup to include other files.

Syntax

The syntax is (with no leading space):

#include path/to/file

The directive can be placed anywhere in the muse body (not in the header, where it would be just a custom header line).

The file content is included as is before any parsing, and will be transparently parsed after being included.

To include a muse document you would just do:

Here starts the body....

#include path/to/muse-document

Here it continues....

And to include, e.g., a configuration file:

{{{
#include examples/file.conf
}}}

The markup surrounding the inclusion will include it as a verbatim snippet.

Please note that including files with a .muse extension will likely trigger a harmless warning, suggesting to place it in another path. For this reason the suggestion is to avoid the use of the .muse extension for inclusion, while reserving it for full documents. Anything else (like .txt or .muse.inc) or no extension at all will do.

Path

Included paths are searched in the directories (possibly multiple) set site-wide, just like a binary is searched in the PATH variable, and the first match is used.

If the site sets, e.g. /etc as a include path (which for sure is not a good idea), this would include /etc/passwd and /etc/apt/sources.list

{{{
#include passwd
}}}

{{{
#include apt/sources.list
}}}

Enabling

This feature needs to be explicitly enabled on the CLI with the provided command amusewiki-include-path. On Debian this can be called with amusewiki include-path, while when installed from Git it can be called, e.g., as:

carton exec "script/amusewiki-include-path --help"

The typical usage would be:

amusewiki-include-path --site testsite --repo

Which will add the site repository itself to the include paths, so you could have a include directory where you can keep the shared files.

On a git pull, included files are checked for freshness and a rebuild is triggered if needed.