Skip to main content


pymd is a command line wrapper for Python Markdown library but having a full HTML file instead of only what it is originally parsed.

It also includes:

  • Batch process files (in folder or in a .list) with .md, .txt or .markdown extensions
  • Specify an output folder (with automatic creation)
  • Includes all the extensions installed by Python Markdown and you can even specify your own!
  • Merge files into one big HTML or create a little book with navigation links. You can even create your own index!
  • CSSed: leave the no-so-ugly embeded CSS (you can even switch between sans and serif fonts) or link to one of your own if you prefer.
  • Headers for files! So you can share the same metadata (like your beautiful name and the creative title of your work) in all the files or when you merge the files and forgot to include the main title of your project.
  • Wiki links: [](file|path) -> [title linked file](output_path)


The syntax is the following: SOURCE [--output FOLDER [--flat]] [--header FILE ] [--exts LIST ]
            [ --css FILE | --serif ] 
            [ book [--index FILE --nav] | merge [--toc(0, 1, 2, 3, 4, 5)] ]

File, folder or .list. A .list is a file that contains the paths to files in order to be parsed.
--output FOLDER, -o FOLDER
Output folder
Don't keep folder structure
--header FILE
Header file, mainly for merged. Could contain title, date and toc (as [TOC_HERE]). Necessary if the header file is not named _index.txt/.md/.markdown in the folder or .list.
List of other installed extensions
--css FILE
Custom CSS with path (as included in href). Default: embeded
(embeded CSS) pick sans (False) or serif (True). Default: False
--merge, merge
Merge files into one.
TOC max depth (for [TOC_HERE]). Default: 0 (all). Options: 0, 1, 2, 3, 4, 5
--book, book
Make a book with navigation (next/prev) and index
--nav, -n
(For book) use titles in navigation
--index FILE
Custom index file for book. Can use wiki links. Necessary if the index file is not named _index.txt/.md/.markdown in the folder or .list.

book automatically creates an index linking to all other files, unless you specify a custom one with --index. By default, it uses "next/previous" links for file navigation. However, you can use -n to use the titles of the documents:

Example of navigation links with titles

You can also use a header file. This is just a normal file with metadata: main document/project title, date, comment, etc. as in a meta-data block; this is the file where the script searches for [TOC_HERE] (useful when merging). An example:

Title: Word domination project
Summary: Ideas for the word domination project
Comment: Missing budget list


Example of the header file

Note how the meta-data is parsed:

Metadata HTML
Title <h1 class="title">
Author <h2 class="author">
Date <h3 class="date">
Summary <p class="summary">
Comment <p class="comment">
the rest as a definition list

If you want to change the depth of the TOC, just use the --toc [number] option. Here's an example showing only the first level:

Example of TOC showing first level


pymd 0.5.5
Also on Github

Python >2.7, Python 3


Version 0.5.5

  • Modified configuration: now global
  • fix relatives paths (book)
  • Wiki links to local files must use [](file| syntax

Version 0.5.4

  • code refactoring: to classes, def changes, vars...
  • fix bug when using a .list & output folder (not having name)
  • python 3.3 compatibility

Version 0.5.3

  • check book pages for navigation (if only one file, disallow)
  • fix book navigation bug (having 2 files, and linking next with the 2nd, when shouldn't)
  • fix: output path with one file
  • fix: finding H1 HTML tag
  • files are saved according to source dir tree
  • option to save files in one depth directory
  • relative links for book
  • wiki links parsing ([](path) -> [title linked file](output_path))
  • custom index for book
  • minor python 3 compatibility
  • toc depth filtering
  • navbar: change css, style links, titles for navbar (option)
  • better handling for merge/book options
  • fix: command line options

Version 0.5

  • fix bug in output folder (merged files)
  • book support (resulting html files will have navigational links)
  • User can specify installed extensions
  • output folder support, with folder creation
  • fixed bugs
  • html5fying

Version 0.3

  • .list support (convert & merge files according order)
  • filter files to parse by extensions

Version 0.2

  • add merge option
  • add embeded CSS

Version 0.1

  • Created