My Journey with markdown

Image Credit https://github.com/dcurtis/markdown-mark

This post outlines my experience with markdown & how its integrated in my workflow. This is specially useful if you are starting with markdown and / or want to see how others use markdown. For someone who doesn’t know what’s markdown this could be a simpler path to get the right direction.

Markdown for uninitiated is a plain text formatting syntax. Read more details here

Why i like it

1. Plain text
2. highly compressible
3. easily archivable
4. Git/version controllable

and overall easy to manage

So this makes it an ideal solution for using as a replacement of conventional documentation softwares. Lets look at what i have as a requirement and what i was using before markdown.

1. notes taking : combination of notepad files, evernote, Google Keep an more.
2. Writing blogposts: WordPress GUI Editor, Texteditors
3. Creating presentation: Powerpoint
4. Sharing information
   • via wiki (collaborative editing) : dropbox or google drive or whatever seems workable option.
   • via website (self managed / github pages) : WordPress or hand coded HTML.
5. Mindmapping: Freemind / Freeplane or mindmeister

Except Mindmapping i have been able to find markdown way of doing things for everything else. Another beauty of markdown being text based is that you don’t need speciallized text editors and any text editor should just work.

Notes Taking

Although this could be done by any software however having a easy way to visualize the notes you have taken acts as a big help. For this again we have multiple options. Based on my experiments this is what i use.

• For Mac: iAWriter / MoU
• For Linux: UberWriter
• Cross Platform: Sublimetext or Atom : Both via Markdown plugins to get help otherwise as a plaintext editor.

BlogPost

Multiple WordPress plugins are available which support markdown

• WP-Markdown-Editor
• JetPack

Note: for markdown style of post’s its essential that you disable the visual editor or do all editing in text mode.

Presentation

For presentation we needed an awesome graphics and visual effect software and i did found Reveal.js. However the workflow for reveal was more centered around either writing your own html or using convertors like pandoc.

However i wanted a straight forward workflow where my base should be markdown and i have minimal intermediary steps. This gave birth to my own framework: Present – revealjs workflow automation

This allows simple and quicker markdown based presentation generation. The workflow tool also insure that browser is launched when everything is ready or if required generating PDF etc.

More details are available here

Sharing information

Wiki

I was looking for a way to share data among multiple folks. However i also wanted it to be easy to manage and simpler to work with. So effectively my requirements were
1. Wiki style data presentation
2. Git / any other backend but it will contain, plaintext / markdown.
3. a GUI editor for page editing.

The search led me through various markdown / text based wiki solutions including but not limited to docuwiki and various python / php / perl / node based implementations.

My search finally ended with gollum, a product by folks from github. The setup is vary smooth with minimal hickups to get started.

However gollum by default works as a single person wiki and doesn’t have authentication module by default. This could be changed and i have made process simpler by placing startup scripts and user auth section in one place.

Website

I am routinely placing large chunk of data online. This is where i am stuck with various arcane ways of storing / modifying data that’s available online. This is where i was again looking for alternatives and mkdocs comes to rescue in this case.

mkdocs has many awesome features out of the box and allows for a quick work. However this brings the question about how to render it and ensure when someone modifies in his / her way but we still maintain same environment.

Solution

We combined power of mkdocs along with travis-ci and build site using mkdocs build --clean. This technique is used to place content in master branch but via travis-ci for every commit on master a version of site is build and is deployed automatically.

An example of this technique is here

Although mkdocs gives most of the stuff by default however what if someone wants some customization or even submit a pull request. Hence i was again in a situation where more customization is required and hence mkdocs default theme is forked as mkdocs-reloaded and will have these additional features.

Mindmap

As i said earlier, i am still looking for a good non fancy Mindmap alternative which can generate mindmap either via direct markdown or via html generated via markdown.