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 free tools to convert your HTML to Markdown to convert HTML documents to the Markdown format.

4 Main Reasons Why Markdown Documentation is the Way to Go

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)

4 ways this GitHub documentation can help in your Power BI Projects;

The GitHub wiki allows you to write in Markdown and reuse the same formatted text in Markdown files you can include with your project.
Markdown is everywhere and is future-proof. Your technical and development teams are most likely using Markdown in their development workflow.
Having a place for documentation within your source course can help during a Power BI Project Management Planning and delivery.
Your Power BI analytics project data preparation code may be housed in GitHub, and having a central place for documentation is a must.

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 on 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. Two tabs switch from Write and Preview modes, allowing you to see how your document looks.

If you do not write in Markdown, a couple of options are listed below. Markdown is useful as you can 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 HTML 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 forget to save the Markdown file in your repository so that the user downloading your GitHub project also has a copy.

Conclusion

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

Resources

A second website that offers Free Markdown to HTML Converter.