Michael Sokol

As a developer using Github, we often find ourselves browsing other people’s code. Sometimes it’s out of curiosity, sometimes it’s because we need to make a maintenance task, but in either case, it’s something valuable because peer review is a fantastic way to gain experience.

I think the code browsing experience could be even greater if the code was written directly for humans, if it was “literate”. It would allow the code:

• To be written like it was a technical report, or a novel
• To be divided into parts, each having a title
• To have an introduction describing each parts of the code, with clickable links to the code portion
• To have a table of content at the beginning, and an annex at the end
• To have the documentation tied in
• To adopt the literate programming style

Github has a fantastic Markdown rendering engine that is applied on each markdown files. Markdown allows you to define titles, links, code blocks, and so much more. It is a perfect candidate for writing literate programming code. It is also much more easy to grasp than LaTex for beginners.

By writing code in Markdown, using the code blocks syntax, it is possible to leverage literate programming on Github.

Of course, Markdown files can’t be executed, but by having a tool that extracts only the code part of the markdown file, and nothing more, we have a valid source file ready to be executed.

I created this tool, you can find it here: https://github.com/mikaa123/lilp

Here is an example project written in markdown: https://github.com/mikaa123/lilplateform

Would you consider source-files written in Markdown to be more readable? What are your thoughts on it? I’m curious to hear what you think (@_ms123)

Cheers!