Whole site compilation of markdown/pandoc? [closed]

Question

Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.

---

Want to improve this question? Update the question so it's on-topic for Stack Overflow.

Closed 4 years ago.

Improve this question

With Sphinx-doc, you can create a bunch of ReStructureText files, with an index.rst file which includes a table of contents macro that auto generates a table of contents from the other included files, and a conf.py that acts as a compilation config. You can then compile the lot into a single python-doc-style site, complete with index, navigation tools, and a search function.

Is there any comparable tool for markdown (preferably pandoc-style markdown)?

Answer 1

Some static site generators that work with Markdown:

• Jekyll is very popular and also the engine behind GitHub pages.
• Python variants: Hyde or Pelican
• nanoc (used f.ex. in the GitHub API documentation)
• Middlemanapp: maybe the best one?

I think none of them use pandoc (maybe because it's written in Haskell), but they all use an enhanced Markdown syntax or can be configured to use pandoc.

Other interesting ways to generate a site from markdown:

• Markdown-Wikis that are file based: f.ex. Gollum, the Wiki-Engine that is also used by GitHub
• Telegram: commercial; written by David Pollak, the inventor the Lift-Scala-framework

Engines that use Pandoc:

• Gitit: Pandoc Wiki
• Pandoc-Plugin forIkiwiki
• Yst static site generator
• Gouda - generates a site from a directory of markdown files
• Rippledoc - generates a navigable site from nested directories of markdown files

The definitive listing of Static Site Generators

A good overview of static site generators: http://staticsitegenerators.net/

Answer 2

Pandoc, the GNU make and sed commands, sprinkled with some CSS are all you need to fully automate the creation of a static website starting from Markdown.

Pandoc offers three command line options which can provide navigation between pages as well as the creation of a table of contents (TOC) based on the headings inside the page. With CSS you can make the navigation and TOC look and behave the way you want.

-B FILE, --include-before-body=FILE

Include contents of FILE, verbatim, at the beginning of the document body (e.g. after the tag in HTML, or the \begin{document} command in LaTeX). This can be used to include navigation bars or banners in HTML documents. This option can be used repeatedly to include multiple files. They will be included in the order specified. Implies --standalone.

--toc, --table-of-contents

Include an automatically generated table of contents.

--toc-depth=NUMBER

Specify the number of section levels to include in the table of contents. The default is 3 (which means that level 1, 2, and 3 headers will be listed in the contents).

As a matter of fact, my personal website is built this way. Check out its makefile for more details. It is all free-libre open-source licensed under the GNU GPL version 3.

Answer 3

If you're OK not using Pandoc, mkdocs would seem to fit your needs.

If you definitely want to use Pandoc-flavoured Markdown, you could check out pdsite. I wrote it as a way to get mkdocs-style site generation with more input formats (like emacs org-mode) and without the Python dependencies - you pass in a folder of Markdown files and get out an HTML site (including automatically-generated multi-level navigation links). It's similar to Serge Stroobandt's approach in that it's just a shell script (it does require you to have tree installed however). Unfortunately it doesn't have a search function yet, although that wouldn't be too hard to add...