How can I export Markdown documentation to different formats?

Question

Writing Documentation

As a developer, I've been looking for the easiest way to write and update documentation. Not a boring text that screams "don't read me", but something happily (and easily) formatted with extra easy support for code.

From LaTeX to wiki to Markdown, just to name a few, I think Markdown is about as close as it gets. But the document itself is very nerdy and not very portable. This will need to become HTML and PDF.

Markdown Editor

So basically I am looking for an editor, converter, or any clever trick I haven't thought of, to turn this documentation into HTML and PDF.

Hands down the simplest editor I have found is StackEdit, but it doesn't export HTML well; it depends on online stylesheets that aren't linked properly and the exported HTML is pretty unbearable to see. It wouldn't work offline anyway.

Export HTML and PDF

I am looking for any way to do this properly. I don't mind if there's some stand alone application or script that converts the markdown file into proper HTML. I need someone to show me the tricks in documentation-generating that I can't find.

PDF is a different story. I think I spammed my computer full with HTML-to-PDF converters, and each of them added spam and watermarks to my awesomely clean documentation.

Solution 1

For choice of output formats, you probably can't beat pandoc - it will convert Markdown (and many other formats) into HTML, PDF, DocBook, and a number more. Its defaults are fairly sane, but you can include your own templates easily enough if you wish. It also has support for language-specific code highlighting in blocks.

Solution 2

The following letters are to denote some common features:​

• M: Mathematical formula syntax support

• G: GitHub Flavoured Markdown

• L: Live Preview

• C: Syntax highlighting for code

• E: Export to various formats

• S: Custom Styling i.e custom CSS for HTML, etc.

• P: Support for plugins

• F: Free

• D: Active development

Here they come (in no specific order):

1. Remarkable

Simple, elegant, feature-rich D F L G S P M C E(pdf, html)

2. ReText

Simple, supports both restructured text and markdown D F M P E(html, odt, pdf)

3. UberWriter

Minimal and lightweight F C M E(pdf html rtf)

5. Typora

Simple, elegant F(while in beta) D G C M L E(html pdf epub docx odt etc.)

6. Haroopad

Feature-rich, beta editor for blogging and mailing, import many formats F G L M E(html)

7. Mark My Words

Simple F D L E(pdf html)

8. Gitbook Editor

For documentation, digital writing and publishing D F G L C M E (HTML PDF epub mobi)

9. Abricotine

Editor based on web technology L F D G C E(HTML) M S

10. GhostWriter

Simple, distraction-free, robust F G D E (HTML , other formats by extensions), S

11. Caret

Minimal, robust D L G C E (PDF) M S

13. Elegant Markdown Editor (EME)

Minimal, simple D L G C E (PDF) M

14. Plugins

The following are plugins available for various IDEs and editors. Some have plugins to convert to HTML or PDF. Check them out.

• Atom

• Vim: Instant-Markdown Plugin

• Bracket: MarkdownPreview Plugin

• Sublime Text: Markdown Plugin

• GNU Emacs

• Visual Studio Code

• Notepadqq

• Jetbrains IDEs: Markdown Navigator

• Qownnotes

Solution 3

Just to complement the previous answers:

I found this online Markdown-to-PDF converter. But there are some downsides to using online services. Not only can they taint the PDF (free lunch?), but they also won't incorporate local images into your document.

Here's an offline Markdown-to-PDF converter called Gimli, but it runs on Ruby.

There's also another offline converter MultiMarkdown to PDF, but it uses Windows instead.

Solution 4

Have you considered Doxygen? Doxygen will output in multiple formats (all at once if you want). I typically use it to generate an HTML manual.

Doxygen is primarily designed to document code, but if you're just writing a standalone manual the page- and section- related commands will do a pretty good job.

The list of Doxygen output formats is here.

Details from the Doxygen Manual page:

PDF: Generated from the LaTeX output by running make pdf in the output directory. To improve the PDF output, you typically would want to enable the use of pdflatex by setting USE_PDFLATEX to YES in the configuration file. In order to get hyperlinks in the PDF file you also need to enable PDF_HYPERLINKS.

Note: You'll need a TeX setup to use this. Doxygen won't produce the required output just by itself, but that applies to Pandoc too.

Solution 5

The editor Atom has a plugin to preview Markdown files (.md) which comes with an export as HTML feature.

View more solutions

Comments

[Redsandro]

This seems to be what I might be looking for. Give me some time to check it out and see if I'll accept your answer. :)

[Redsandro]

No, I didn't know they could do markdown. I think it's relatively new. I've been googling around but no one seems to provide an example command for converting markdown to pdf. Can you edit an example into your answer?

[Redsandro]

Can you add an example command for converting markdown to pdf using pandoc into your answer?

[Redsandro]

pandoc -f markdown -o test.pdf test.md. Your answer is correct but I find the output rather plain/old/boring/ugly comapred to 21st century implementations like gitHub and Stack Overflow.

[Cheeseminer]

@Redsandro Is that what you wanted? PS. there are links under the words 'here' and 'page' - not very obvious in this font.

[Redsandro]

Thank you for the edit. I upvoted your answer. However, I'd like to see the specific command relevant to this question as well, which involves converting Markdown to PDF. E.g. pandoc -f markdown -o test.pdf test.md for pandoc. I would command with an example myself, but for Doxygen I can't seem to find it; all examples seem to start from LaTeX output, as if I need to convert Markdown to LaTeX first. BTW, I don't know how pandoc vanilla works, but with the package from Ubuntu it works immediately, no need to add TeX setup manually.

[Cheeseminer]

Doxygen uses a config file rather than command line parameters like pandoc does. So, having got Doxygen, you need to configure the file "doxyfile" for GENERATE_LATEX = YES (and other basic configuration, like INPUT) and then run doxygen doxyfile. This should generate the LaTeX from the markdown. I'm on Windows, looks like Ubuntu is more set up for this sort of thing (unsurprisingly).

[spirit]

...and it has plugins which allow you to export to PDF. Search the packages for Markdown to PDF.