Github Wiki Markdown tips and examples
Some slick and simple Github Wiki tips that will improve your documentation and overall usability!
Why should I ?
Whether its an open source project or internal docs for your coworkers, people appreciate good quality documentation for software and it’s a guaranteed way to quickly improve usability and overall presentation of your code.
Research has shown that readers find it difficult to process large blocks of text. That’s why it is crucial to break up your docs with paragraphs, page breaks columns, bullet points etc.
Headers & Internal Links
Using Headers and internal links is a great way for users to easily find different content in your documentation and produces a sleek effect.
Use # to create a H1 heading. Use multiple ## to create subheadings.
[] Creates a title followed by (), the contents of which acts as a link to where you want the title link to go. We need to use ‘-’ instead of a space every time when creating title links.
You can see this in action on the Repo!
# Table of Contents
1. [Topic Title](#Topic-Title)
2. [Topic subtitle](#Topic-subtitle-1)
3. [Topic subsubtitle](#Topic-subtitle-2)
4. [Topic subsubsubsubtitle](#Topic-subtitle-3)# Topic Title
## Topic Subtitle 1
### Topic Subtitle 2
#### Topic Subtitle 3
Steps and Bullet Points
Using steps and bullet points area great way to break up information in a piece of text or to focus your readers focus on a particular aspect.
Generally, we use steps when we want the user to go through a process in a specific order and bullet points when the order is not relevant to the task.
To create a step list we just use numbers and a full stop, for a bullet point list we use * .
1. Step 1.
2. Step 2.
3. Step 3….
4. Step 4….
5. Step 5….* This is a bullet point
* This one too
* Also this!
Quotes
Quotes are useful for a variety of reasons, use quotes to add context or theme to your documentation. We use > followed by text to create quote block.
> Text for a quote —
> A noble spirit embiggens the smallest mind. — Jebediah SpringfieldText for a quote
A noble spirit embiggens the smallest mind. — Jebediah Springfield
Columns
Columns can be a slightly tricky aspect of Markup but they can be incredibly useful to focus the readers attention on a series of important aspects to your documentation.
Set the column text by separating columns using ||.
Use ‘- -’ followed by | to create the column and number of columns.
| col1 | col2| col3 |
— — | — — | — -
Tables
Tables are an awesome way to display information. The biggest advantage of adding a table to a document is providing a visual grouping of information. While you could simply type rows of data, the straight lines of a table direct the reader’s eye and show a clear change where chunks of text may not be as clear.
Use || and * to set the titles of the rows and columns.
Then use ‘- -’ and || to set the number of columns.
Use || again to bracket pieces of text in the table.
| **Information type** | **Description** |
— — | — -
| info one | this is the first part of the description element of the table |
| info two | this is the second part of the description element of the table |
| info three | this is the third part of the description element of the table |
Images
images an be a great way to highlight something in your documentation or show updates in newer versions. Can also be used as a fantastic way to show step by step processes.
Github have now made it quite easy to upload an image to your repo. SImply drag and drop your image to the upload field in the bottom of the wiki from your folder or else click the ‘image’ icon to include an outside weblink. Then you can use this code snippet to include an image and alt text
Use this code to include an image already uploaded to the repository
Example:
Video
Video can be a great way to include a presentation of what your documentations should ultimately look like, or else provided more supporting guides to your users.
To include a video from an external source such as Youtube, we can use some simple HTML included in the code snippet below.
We can change the width by changing the ‘style’ element.
<div align=”left”>
<a href=”VIDEO LINK HERE">
<img src=”IMAGE LINK HERE" style=”width:100%;”>
</a>
</div>EXAMPLE:<div align="left">
<a href="https://www.youtube.com/watch?v=Z-vZuBX0Cmk">
<img src="https://upload.wikimedia.org/wikipedia/en/e/ed/Nyan_cat_250px_frame.PNG" style="width:100%;">
</a>
</div>
So many more options
This is just a small taster of what is possible on Github Markup. I found these to be some of the most useful but there are plenty more.
Use these elements to enhance your documentation and create a product that is clear for all users. Your users appreciate good documentation and it makes your end product stand out even more.
You can find all of these examples and even a few more over on the Repo.
Hope you have a great day and until next time!
-Alan
