Convert a markdown file to a series of HTML files

Question

Say I have a manual for a computer program written in markdown/org-mode format. The manual is written as a book with chapters, sections, and subsections.

I know Pandoc can convert this Markdown file to HTML. But what if I want to convert each chapter (say) into its own HTML page and link to the next and previous chapter or section?

For instance consider the website documenting SWIG. http://swig.org/Doc3.0/Sections.html This is precisely the structure what I would like the output of Pandoc to be on my markdown file.

I know latex2html can do this, for Latex files, and that Pandoc can convert markdown to latex, but I don't like the resulting output. I would prefer a pure pandoc solution not involving any external programs.

Answer 1

This is not entirely trivial. A good approach would be to write a custom HTML template to be used by pandoc.

% pandoc -D html > my-page-template.html
# edit my-page-template.html to your liking

That template could include links to the previous and next page, if any.

$if(next-page)$<a href="$next-page$">next</a>$endif$

The respective file-names would be passed via the command line, so pandoc can insert the correct values.

pandoc -M next-page=introduction.html --template=my-page-template.html …

A wrapper script written in shell or some other scripting language would probably be useful.

---

As you see, this can become quite a bit of work. Fortunately, somebody already did all this and packed it up in an R package: bookdown. It produces great looking output, and I recommend it highly.