There are many formats that you can write documentation in for the Web.  For GitHub projects, Markdown is an accessible format that is cross-platform and compatible with many web editors and CMS systems.  This article shows how to add a Wiki to your GitHub project, write in markdown, or use Dom Christie’s HTML to Markdown to convert HTML document to the Markdown format.

Why Markdown

The Wikipedia definition is the best I have seen as to why using Markdown is the option for cross-platform documentation.   “Markdown is a lightweight markup language with plain text formatting syntax. The format is designed so that it can be converted to HTML and many other formats using a tool by the same name.” (Wikipedia)  The GitHub wiki allows you to write in Markdown, allowing you to re-use the same formatted text in markdown files you can include with your project.

You should always add documentation to your projects, especially when the tools are built into each project. In each  GitHub project, one of the tabs is labeled Wiki which exposes a built-in Wiki editor.

Start Your First WIKI Page

Once in your site, selecting the Wiki tab will display the Create Your First Page button which you click to start the process.

GitHub WIKI Tab

You will then see the page editor. There are two tabs, that switch from Write and Preview modes which allows you to see how your document looks.

Editor Screen

There are a couple of options if you do not write in Markdown, which is listed below.  Markdown is useful as you can also reuse the code to add a .MD file to your project so that anyone doing a check out can have instructions or documentation with the code.

Options for the editor

Convert Your HTML to MarkDown

I write many of my articles for the Web and use markdown as the starting point in Ulysses on a Mac. However, once in WordPress I make edits and use Grammarly to fine tune and do final edits. This makes the final version in HTML format. What I want to do is make this final version also in Markdown. A great site, by Dom Christie, has a javascript library that translates HTML to Markdown and a sample, pictured below, at To-Markdown.

I used the site pictured below to translate my final blog post back to markdown by pasting it into the left column and copying the results on the GitHub editor’s right.

To Markdown

Finished Result

The results below are the final version of the documentation.  The key was that I was able to take HTML, translate it to Markdown and create the start of a Wiki.

Wiki Tab on the GitHub Project site

As pictured above, this creates user-friendly documentation. Don’t forget to also save the Markdown file in your repository so that the user downloading your GitHub project also has a copy.

After discovering the tab, I have started using this feature to include documentation and project info with my repositories rather than solely relying on my website. However, having your own website also has its advantages.

I hope this helps as the importance of documentation on a positive user experience cannot be overlooked.

Published by Steve Young

Cloud Solution Architect at @Microsoft specializing Data & AI . Posts = my views, not the views of my employer View more posts

Leave a comment

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Exit mobile version