tbnorth / pymd_helper

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

pymd_helper

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

• Overview
• Available commands
  • Insert a file insert
  • Insert a table of contents toc
  • Insert documentation about this documentation system documentation
• How it works
• Similar tools
• To do

Overview

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.

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