Usage
Once this plugin is installed, just replace
the plugin name simple
with semiliterate
in your mkdocs.yml
file.
It accepts all of the same parameters, so mkdocs
will still work as before,
and you will have immediate access to all of the following extensions.
(Note that this documentation assumes a familiarity with the
usage
of the simple
plugin.)
Inclusion syntax
While extracting content from a file (because it matches one of the
semiliterate
patterns, rather than just include
),
an unescaped expression of the form
{! FILENAME YAML !}
(which may span multiple lines) will trigger file inclusion. The FILENAME may
be a bare word, in which case it cannot contain whitespace, or it may be
enclosed in single or double quotes. Note that FILENAME is interpreted relative
to the directory in which the file containing the {! .. !}
expression
resides. The YAML is interpreted exactly as the extraction options to a
semiliterate
item as
documented
for the simple
extension, subject to the extensions below. The text
extracted from FILENAME is interpolated at the current location in the file
currently being written. Recursive inclusion is supported.
The simplest example of such an inclusion directive is just
{! boilerplate.md !}
, which (because of the conventions for extraction
parameters) simply interpolates the entire contents of boilerplate.md
at the current location.
For an example that uses more of the extraction parameters, the current version number of mkdocs-semiliterate is extracted into the Overview of this documentation via
{! setup.cfg { extract: {start: name}, terminate: '(\d*\.\d*\.\d*)', ensurelines: false} !}
to take advantage of the beginning of the setup.cfg
file:
[metadata]
name = mkdocs-semiliterate
version = 0.8.3
description = Extension of mkdocs-simple-plugin adding easy content inclusion
...
(and of course both of the code snippets just above are extracted into this
page with {! ... !}
, as you can see in the
source code
for the plugin.)
Note that a {! ... !}
directive must be in a line that semiliterate would
normally copy. That is, semiliterate does not examine lines after
the terminate
regexp, or when no mode of extraction is active.
It also doesn’t check any text written from lines that match these
special expressions, including start
and stop
.
Moreover, on such normally-transcribed lines,
it’s the text after the application of any semiliterate replace
ments that
is checked for {! ... !}
.
Double-quoted filenames and special extraction
Standard Python escape sequences in double-quoted filenames are interpreted as usual; for example you can write
{! "snippet/Say \"Don\'t\"" !}
to include a file whose name (snippet/Say "Don't"
, in this case) has both
double and single quotes.
Further, semiliterate
supports some special escape sequences for
doublequoted file names to include text from other places than current files
in the project tree:
\git
: extracts a version of a file from the Git archive of the project
(presuming it is under Git version control) and then
includes content from that file. For example, you could write
{! "\git 0.1.0:mkdocs.yml" extract: {start: '### install'} !}
to extract content starting after the ### install
line from the
mkdocs.yml
file in the Git commit of this repository
tagged 0.1.0
. This feature is primarily useful if you are documenting the
development or changes to a project over time, or are documenting a feature
in a specific past release of your project, and want to be sure that
material included in your documentation does not change as the project
progresses. (This behavior is as opposed to the usual case, in which you want
your documentation to incorporate the most up-to-date version of extracted
content.)
The precise behavior for a FILENAME argument in a {! ... !}
inclusion of the
form
"\git SPECIFIER"
is that the output of git show SPECIFIER
is written to a temporary file,
and that file is extracted from.
\syspath
: searches for the remainder of the doublequoted filename in the
python sys.path
and includes content from the found file. For example, you
could write
{! "\syspath mkdocs/themes/readthedocs/base.html"
extract:
replace: [ ['([<]body.*$)', '\1\n<p>Kilroy was here.</p>\n'] ]
!}
to create a version of the “base.html” of the “readthedocs” theme with
additional content at the very top of the body. As the example suggests, this
mechanism is primarily useful to tweak an mkdocs theme in ways not
anticipated by the {%- block ... %}
directives placed by the theme writer.
Additional plugin parameters
semiliterate
adds a couple of new plugin parameters to further tailor its
behavior as compared to simple
. They are described in this section, with
default values in parentheses at the beginning of each entry.
- exclude
- ([‘.o’])
Files whose name contains a string in this list will not be
processed by
semiliterate
, regardless of whether they might matchinclude
, thesemiliterate
patterns, or standard Markdown. - copy_standard_markdown
- (False)
Whether to add MkDocs’ list of standard Markdown extensions to
the
include
parameter so that Markdown files will be directly copied to the docsite. Note that thesimple
behavior corresponds to a true value forcopy_standard_markdown
, butsemiliterate
still incorporates all standard Markdown files because of the followingextract_standard_markdown
parameter. - extract_standard_markdown
- ({})
If the
enable
key of this dict parameter is true (it defaults to the opposite ofcopy_standard_markdown
), it adds a semiliterate block causing extraction (and hence include-directive processing) from all standard Markdown files (as defined by MkDocs). The remaining keys of this parameter are included as parameters of that semiliterate block. Thus, the default values of the parameters arrange for Markdown files to be copied “as-is”, except possibly for embedded inclusions. On the other hand, setting this parameter to{enable: false}
(which is also the default whencopy_standard_markdown
is true) will prevent automatic extraction (and hence disable inclusion-directive processing) from standard Markdown files. - extract_on_copy
- (False)
Whether to also attempt extraction from a file that is copied
verbatim (because of matching the
include_extensions
). - semiliterate.ensurelines
- (true) Guarantees that a newline is trancribed for each line of the input,
even if a start, stop, terminate, or replacement pattern would have
suppressed the newline. Note this can be set separately for each block
(i.e. filename pattern) within the semiliterate parameter. The default
setting corresponds to the
simple
behavior, so setting this to “false” allows you to suppress newlines with judicious use of these patterns.
Adjusting the mkdocs theme
semiliterate
also makes it possible to add generated files to the mkdocs
theme. It does this by detecting if a theme.custom_dir
parameter has been
set in the mkdocs configuration, and if so, it adds the corresponding
directory in the generated docs dir to the theme search path. (Note this
means that
files in the corresponding subdirectory of your project will be copied into
the resulting doc site unless their names start with a ‘.’)