Skip to content
5MinuteBI Creating Data Power Users 5 Minutes at a time

5MinuteBI

Creating Data Power Users, 5 Minutes at a Time

  • Home
  • Blog
  • About
  • Contact

How To Add a Wiki to Your GitHub Project Using Markdown​

BySteve Young Updated onJuly 29, 2023

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;

  1. The GitHub wiki allows you to write in Markdown and reuse the same formatted text in Markdown files you can include with your project.
  2. Markdown is everywhere and is future-proof. Your technical and development teams are most likely using Markdown in their development workflow.
  3. Having a place for documentation within your source course can help during a Power BI Project Management Planning and delivery.
  4. 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.

GitHub WIKI Tab
GitHub WIKI Tab

You will then see the page editor. Two tabs switch from Write and Preview modes, allowing you to see how your document looks.

Editor Screen
Editor Screen

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.

Options for the editor
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 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.

To Markdown
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
Wiki Tab on the GitHub Project site

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.

Related

Steve Young

With over 34 years of experience in the data and technology industry, the last 16 with Microsoft, I have had the opportunity to work in various capacities, contributing to my knowledge and expertise in Data Engineering, Power BI, and Data Visualization.

Facebook Twitter Instagram YouTube Linkedin Pinterest

Meta

  • Log in
  • Entries feed
  • Comments feed
  • Powered by WordPress.com.

Disclaimer: The views expressed are my own. I offer no guarantees for the accuracy of the information shared, and it is for educational purposes only.

All non-original photography is sourced and licensed from my account on PEXELS,  STORYBLOCKS, iStockPhoto, and Pixabay. Please use our Contact Page if you have a question.

The information provided on this blog is for educational purposes only. Steve Young is not responsible for any errors or omissions or for any actions taken based on the information provided on this blog.

© 2023 5MinuteBI

This website uses cookies to improve your experience. We'll assume you're ok with this, but you can opt-out if you wish.Accept Read More
Privacy & Cookies Policy

Privacy Overview

This website uses cookies to improve your experience while you navigate through the website. Out of these, the cookies that are categorized as necessary are stored on your browser as they are essential for the working of basic functionalities of the website. We also use third-party cookies that help us analyze and understand how you use this website. These cookies will be stored in your browser only with your consent. You also have the option to opt-out of these cookies. But opting out of some of these cookies may affect your browsing experience.
Necessary
Always Enabled
Necessary cookies are absolutely essential for the website to function properly. This category only includes cookies that ensures basic functionalities and security features of the website. These cookies do not store any personal information.
Non-necessary
Any cookies that may not be particularly necessary for the website to function and is used specifically to collect user personal data via analytics, ads, other embedded contents are termed as non-necessary cookies. It is mandatory to procure user consent prior to running these cookies on your website.
SAVE & ACCEPT
  • Home
  • Blog
  • About
  • Contact