Python GitHub Markdown helper - include files in markdown, table of contents, etc.
pymd_helper
uses specially formatted markdown comments (<!-- |cmd,args... -->
) to enrich markdown documentation in git repositories (GitHub, etc.).
pymd_helper
can insert files into code blocks to keep documentation in sync.
with actual code, and generate a table of contents.
<!-- |insert,src=examples/script.sh,syntax=shell,addpath -->
will insert the contents of the file script.sh
in a markdown code block with
shell
syntax highlighting:
# this isn't a real script
ARG1=$1
cp $ARG1 /dev/null
echo "Copy complete"
The presence of the addpath
parameter controls the presence of the
(examples/script.sh)
link
preceding the code block. type=comment
can be added to the |insert
command
line to insert a <!-- -->
comment block rather than a code block.
<!-- |toc -->
will generate a table of contents for the markdown headings (#, ##, โฆ) in the remainder of the markdown file.
<!-- |documentation -->
will insert the following comment in your markdown.
<!-- Please see https://github.com/tbnorth/pymd_helper for instructions on
updating this projects markdown files. `pymd_helper` is used to
insert/update files into markdown documentation, generate tables
of contents, etc.
-->
This comment is not visible to people viewing the repository's rendered markdown, but provides information for people updating the markdown directly.
- write preceding sections
- add line / regex ranges for
|insert
- add docker container for zero install usage on systems with docker
- add tests
- add file recursion in
|toc
generation