How to add a Wiki to Your GitHub Project Using Markdown​

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 documents 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 reuse 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.

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.

There are a couple of options if you do not write in Markdown, which are 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 checkout can have instructions or documentation with the code.

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.

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.

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

After discovering the tab, I 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.