At Leka, we decided that it would be more convenient to use .md for everything we write. Our reasons are simple:
- no need to use Microsoft Word: a simple text editor is enough most of the time
- speed of editing: large files are just text
- ease of formating: no need to find the Header 1 style in the list, you just write
# Header 1 - content and form are finally independent
- you can use your favorite
scmto track, collaborate and manage all your precious documents
Markdown is designed to be easy to write, and, even more importantly, easy to read:
A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. –John Gruber
Of course .md are useless if you want to send your business plan to an investor. That's where Pandoc comes in and let us easily transform our .md files to .docx or .pdf files.
The version of markdown that we use,Markdown Extended by Pandoc, is a revision of the standard markdown by John Gruber.
The Pandoc website has an incredibly rich documentation about this Pandoc Flavored Markdown.
We really recommend you to read this documentation because it might be very useful for your personal project as well.
We will only document our specific aspects and how we use them. We'll be brief and link to the official documentation for further information.
IMPORTANT: Beware if you try to use exotic features like tables, we haven't tried them out yet. Stay tuned for improvements in the future.
From the Pandoc documentation:
Pandoc is a Haskell library for converting from one markup format to another, and a command-line tool that uses this library.
To install Pandoc, you can the installer for your operating system or you can build it from source.
The easiest way is to use the installer that you can download from the installation page.
On Mac OS X, if you want to install it from source, you can do as follow:
$ brew install haskell-platform
$ cabal update
$ cabal install --force pandoc pandoc-citeprocIt's pretty simple:
$ pandoc -sS MyMarkdownFile.md -o MyDocxFile.docxAnd if you have plenty of .md files in the right order that you want to compile together, you can type the following:
$ pandoc -sS *.md -o MyDocxFile.docxIt's pretty simple:
$ pandoc -sS MyMarkdownFile.md -o MyDocxFile.pdfAnd if you have plenty of .md files in the right order that you want to compile together, you can type the following:
$ pandoc -sS *.md -o MyDocxFile.pdfHere after are all the features that we use as is, out of the box, with no specific rules.
Here after are all the features we use in a certain way and that are important to keep consistency in all our documents.
We use headers from 1 to 5.
#--> Header 1##--> Header 2###--> Header 3####--> Header 4#####--> Header 5
Link to Pandoc documentation: Headers
Images can be included inside a .docx document.
You must make sure your images have the right size so you won't have to resize them all in Word. We also recommend putting your images in an img folder inside your project folder.
This repo is a good exemple:
MyDirectory
|-- Part-1-Introduction.md
|-- Part-2-Team.md
|-- Part-3-Product.md
`-- img
|-- MyImage-1.png
|-- MyImage-2.png
`-- MyImage-3.pngBy doing so, you can reference your images this way:
Some paragraph...
Some other paragraph...Link to Pandoc documentation: Images
When writing a report, a business plan or anything else, it's always convenient to put your sources as footnotes.
The raw version of markdown doesn't support footnotes but Pandoc does provide a way to write footnotes for .md and export them as real .docx footnotes for Word.
Here is an exemple from the Pandoc documentation:
Here is a footnote reference,[^1] and another.[^longnote]
[^1]: Here is the footnote.
[^longnote]: Here's one with multiple blocks.
Subsequent paragraphs are indented to show that they belong to the previous footnote.
{ some.code }
The whole paragraph can be indented, or just the first line. In this way, multi-paragraph footnotes work like multi-paragraph list items.
This paragraph won't be part of the note, because it isn't indented.Link to Pandoc documentation: Footnotes
And that's all folks! :)