Skip to main content

Transform markdown files into html with styles of github

Project description


Basically, You may want to convert md files into Html looks exactly like github does.

Maybe you would try pandoc, but html it generates looks not very well.

So, I start writing this small tool, inspired by grip


mdtogh can convert your md files into html files like github does with features belows:

  • toc support
  • index.html for your book
  • next/prev files link
  • file regexp to select your md files
  • fix relative link(ie. <a href=””></a> => <a href=”01.html”></a>)
  • custom template
  • offline renderer(still working)


I’ve generate a book written by julycoding: The-Art-Of-Programming-By-July.

Demo link:

You can check on that.


From pypi

$ pip install mdtogh

Also, you can clone repo & install with

$ git clone
$ cd md_to_github_html
$ python install

Maybe you will need add sudo


Generate one or more files

$ cd mdfiles
    $ mdtogh

Generate all md files in current directory

$ cd mdfiles
$ mdtogh

Generate md files in other directory

$ mdtogh ../mdfiles

Generate files with file reg support

$ cd mdfiles
$ mdtogh --file_reg='^\d.+\.md'

Generate files with toc & toc_depth support

$ cd mdfiles
$ mdtogh --toc --toc_depth=2 --file_reg='^\d.+\.md'

Generate files with additional book info

$ cd mdfiles
$ mdtogh --toc --book='book.json'

The format of book.json is given below.

Generate files with custom template

$ cd mdfiles
$ mdtogh --templates=path_to_templates

The rules for templates is given below.

Recommanded options to generate book

$ mdtogh --css --toc --book='book.json' --file_reg='your reg exp'

Recommanded options to generate several files

$ mdtogh

For more options

mdtogh -h

Something You May Notice

As to generate files exactly like github does, the easiest way is to use api if offers. But it has its own limits.

  • 60 for anonymous requests an hour
  • 5000 for requests using Basic Authentication an hour

So, you may using –user & –pass options

$ mdtogh --user='your_github_username' --pass='your login password'

Your info are sended through https which is safe. mdtogh will not save any of it.


    "title": "Demo book",
    "description": "This is a book.",
    "coverimage": "demo.jpg"

Custom Templates Support

mdtogh now support custom templates. You can use –templates to specific where to locate templates. You should give at least three files belows:

  • content.html
  • toc.html
  • index.html

mdtogh use jinja2 as template engine.

For tutorial of template writing, please check jinja doc

  • content.html

content.html is used for generate standalone html file with things like head, body after content of md file is rendered by github or offline renderer.

mdtogh will pass several parameters to content.html which you can use:

  • filetitle #booktitle in book.json`
  • content #contents after render by `github` or `offline renderer`
  • toc #not support yet
  • needtoc #whether toc is needed
  • prevfile #link to prevfile. only used when `–toc` is set
  • nextfile #link to nextfile. only used when `–toc`is set


toc.html is used for generate table of content which will be used later in index.html. So, you don’t need add html or body tag.

Parameters passed to toc.html.

  • tocs
  • toc_depth


tocs is a list of headers. It’s set like

    ['h1', 'top header', 'headerlink'],
    ['h2', 'sub header', 'header link'],


toc_depth is set by user. It refers the maxium depth of header. It’s an integer value. ie.



index.html is used for generate index.html for book.

Parameters passed to toc.html:

  • booktitle #title in book.json
  • coverimage #coverimage in book.json
  • description #description in book.json
  • toc #toc rendered with toc.html


mdtogh is still on developing.

Features are developing or will be add later.

  • support recursive options.
  • add toc in content.html
  • offline renderer


Any help will be appreciated.

  • open issues if you find any questions
  • complete one in TODO list
  • add features you like
  • feel free to open pull request

Change Log

  • 2014/3/6 0.0.6 add option: –encoding for offline renderer, fix relative link, add support for custom template
  • 2014/3/5 0.0.5 add, fix pacakge wrapped by Fix css link not include while rendering after first downloading css files
  • 2014/3/4 0.0.3 fix error leads by unicode filename
  • 2014/3/3 0.0.2 add –toc_depth support, fix get_html_name bug
  • 2014/3/1 0.0.1 first release


Special thanks to grip. Without its excellent work, this tool can’t be done.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for mdtogh, version 0.0.6
Filename, size File type Python version Upload date Hashes
Filename, size mdtogh-0.0.6.tar.gz (15.2 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page