pymd_helper

Python GitHub Markdown helper - include files in markdown, table of contents, etc.

Overview
Available commands
How it works
Similar tools
To do

Overview

pymd_helper uses specially formatted markdown comments () 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.

Available commands

Insert a file `insert`

    <!-- |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:

(examples/script.sh)

# 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.

Insert a table of contents `toc`

   <!-- |toc -->

will generate a table of contents for the markdown headings (#, ##, …) in the remainder of the markdown file.

Insert documentation about this documentation system `documentation`

    <!-- |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.

How it works

Similar tools

To do

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

tbnorth/pymd_helper