Site Map - skip to main content

Hacker Public Radio

Your ideas, projects, opinions - podcasted.

New episodes every weekday Monday through Friday.
This page was generated by The HPR Robot at


hpr1832 :: Simplify writing using markdown and pandoc

How I use Markdown and Pandoc in my writing workflow

<< First, < Previous, , Latest >>

Thumbnail of Mr. Young
Hosted by Mr. Young on Tuesday, 2015-08-11 is flagged as Clean and is released under a CC-BY-SA license.
markdown, writing, word processor. 3.
The show is available on the Internet Archive at: https://archive.org/details/hpr1832

Listen in ogg, spx, or mp3 format. Play now:

Duration: 00:21:28

general.

Show Notes

I write almost exclusively in Markdown https://daringfireball.net/projects/markdown when writing documents and taking notes. I use the program, Pandoc https://www.pandoc.org to convert markdown to different formats, including odt, docx, and pdf.

The original purpose of Markdown: 1 > Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).

Markdown has since been extended to include more features and functionality. Extended versions include Github-flavored markdown https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet and multi-markdown https://fletcherpenney.net/multimarkdown.

Some of the basic syntax:

  • Headings - use one or more # to make headings
  • bold - use __ or ** for bold
  • italics - use _ or * for italics
  • hyperlinks - use [text](link) for hyperlinks
  • images - ![text](link) for images
  • tables -
    Head1 | Head2 | Head3
    ----- | ----- | -----
    stuff | stuff | stuff
  • lists - use - or * or + at the beginning of a line
  • quotes and code - ` for single code item, > for block quote, tab for block code, ``` for fenced code. Highlighting is available

Pandoc: 2 Pandoc can convert documents in markdown, reStructuredText, textile, HTML, DocBook, LaTeX, MediaWiki markup, TWiki markup, OPML, Emacs Org-Mode, Txt2Tags, Microsoft Word docx, EPUB, or Haddock markup to

  • HTML formats: XHTML, HTML5, and HTML slide shows using Slidy, reveal.js, Slideous, S5, or DZSlides.
  • Word processor formats: Microsoft Word docx, OpenOffice/LibreOffice ODT, OpenDocument XML
  • Ebooks: EPUB version 2 or 3, FictionBook2
  • Documentation formats: DocBook, GNU TexInfo, Groff man pages, Haddock markup
  • Page layout formats: InDesign ICML
  • Outline formats: OPML
  • TeX formats: LaTeX, ConTeXt, LaTeX Beamer slides
  • PDF via LaTeX
  • Lightweight markup formats: Markdown (including CommonMark), reStructuredText, AsciiDoc, MediaWiki markup, DokuWiki markup, Emacs Org-Mode, Textile
  • Custom formats: custom writers can be written in lua

I use Ubuntu because it is the only distro that does not bundle pandoc in the haskell libraries. With pandoc, you can specify the template that you are using, so that the same one document can be formatted quickly in many different ways and file formats.

Workflow:

  1. Write using vim or other text editor. When I was starting, I used a markdown previewer
  2. Create the template for the client
  3. Convert document appropriately

Use markdown for:

  • taking notes
  • creating SOPs
  • Creating User guides (Image Magick mogrify)
  • Creating things for my website

Other programs and tools:

  • Retext
  • Haroopad
  • discount
  • stackedit.io
  • atom
  • texlive for going direct to pdf

Comments

Subscribe to the comments RSS feed.

Comment #1 posted on 2015-08-11 08:01:01 by 0xf10e

thx, very useful

Nice episode, many little things I didn't know about markdown.

While I prefer ReStructuredText* over markdown (just like I prefer Mercurial/Python/Golang over Git/Perl/Java) I have to use it on Gitlab and Github.
So like I said, very useful.

*) and rst2pdf works w/o LaTeX ;)

PS: one of the words you were looking for is WYSIWYG - "what you see is what you get"

Comment #2 posted on 2015-08-12 11:16:31 by Jon Kulp

plus HTML as needed

Thanks I enjoyed this episode. One thing I would add is that whenever necessary you can freely add bits of HTML when the markdown syntax doesn't give you everything you need.

Comment #3 posted on 2015-08-17 18:04:55 by Dave Morriss

Excellent episode

This was a great episode.

I use Markdown and Pandoc myself for all my HPR episodes, though I have not yet moved away from AsciiDoc when writing my own project notes and similar.

A while ago, I had been looking for the best lightweight markup format and was very happy to find Markdown. Then I found Pandoc and very much appreciated its extensions and huge range of features.

Thanks for your great overview.

Leave Comment

Note to Verbose Commenters
If you can't fit everything you want to say in the comment below then you really should record a response show instead.

Note to Spammers
All comments are moderated. All links are checked by humans. We strip out all html. Feel free to record a show about yourself, or your industry, or any other topic we may find interesting. We also check shows for spam :).

Provide feedback
Your Name/Handle:
Title:
Comment:
Anti Spam Question: What does the letter P in HPR stand for?
Are you a spammer?
Who is the host of this show?
What does HPR mean to you?