How to create and edit Github wiki - ZhihengZhou/Software_Engineering_Wiki GitHub Wiki

This page is a tutorial page for Github wiki. This tutorial is based on Github markdown guides[1] and adam-p/markdown-here[2]. Please feel free to have a look for the original site.

In this page, we will talk about how to create a Github page and how to edit it. Below are quick links for different part of this tutorial:

  • How to create, edit, and add new Github wiki page
  • How to add topic/section title
  • How to create ordered or unordered lists
  • How to create internal and external links
  • How to add tables
  • How to add images
  • How to add anchor links

How to create, edit, and add new Github wiki page

First, create a new Github project, then go the the project page in your browser, then you can see:

images/create_wiki.png

In above page, click the "wiki" button in the menu bar, then click the "Create the first page" button. After that, you'll see the edit page in your browser:

images/edit_page.png

In the edit page, you can type any content you want in the edit text block (the largest one). The top text block is for editing the page's title/topic. Please note that the wiki page here use markdown language mainly.

After we finish editing, we can press the preview button to inspect the wiki page. Make sure you have preview the editing and the page is showing what you want before saving the page.

The "edit message" in above edit page is the message you want to add for this edit. It is like the message when you commit codes to Github. Although it is optional, we highly suggest you to add what you have done in this edit in the message. Because it can help the group works.

After you have done all of above step, you can save the page. The "Save page button" is under the edit message block. After you save the page, you will see:

images/edit_and_new_page.png

This is the home/main page of your wiki. In this page, you can press "Edit" button to edit the home page. Or you can press "New page" button to create a new wiki page. The editing for new page is like the home page.

How to add topics/sections

After we have our wiki pages, now we can add some topics or sections title to our wiki.

In markdown, the title normally called "heading". There are six inbuilt size for the heading, from H1 to H6, and the H1 is the largest while the H6 is the smallest.

The character "#" is setting the heading for page. The number of "#" control the size of heading, e.g, "#" for H1 and "######" for H6. After we use "#", the text behind it will be the heading.

For example, the codes for different size heading are below:

# H1
## H2
### H3
#### H4
##### H5
###### H6

And the corresponding effects for above codes in wiki pages are:

H1

H2

H3

H4

H5
H6

Then, you can change the text behind the "#" to your topic title for topic/section title. What is more, since there is a division line under the heading for H1 "#" and H2 "##", we suggest you to use H1 and H2 for your topic/section title.

How to create ordered or unordered lists

Sometimes we want to add lists to our wiki. There are two types of list in markdown:

  • The first one is ordered list, which means there is a numeric label for each item. It is normally used when the items in this list have a order.
  • The second one is unordered list, which means the label for item is not a numeric number. It is normally used when the items in this list are equally important.

The code for above two lists are:

Ordered list:
1. Item 1
1. Item 2
1. Item 3

Unordered list:
* Item
* Item
* Item

And the code will show us:

Ordered list:

  1. Item 1
  2. Item 2
  3. Item 3

Unordered list:

  • Item
  • Item
  • Item

How to create internal and external links

When we constructing our wiki, we may want to add some links in to the page. For now, we would like to introduce you two kinds of the link:

  • Internal links: Links will go to the pages in your wiki/website
  • External links: Links will go to other website (e.g. Baidu, wikipedia)

For internal link, we can use the relative path to redirect:

[Text or description for the link](relative path for the internal link)

For example, in this sample wiki, we have two more wiki pages which are "Home.md" and "The-Australian-National-University.md". Then, the code for redirecting to these pages is:

* [Text for Home link](Home)
* [Text for ANU link](The-Australian-National-University)

And it will show us:

For external links, the grammar is same as the internal link, but we should use the absolute url address as the link. For example, the code:

* [Concept of programming framework in "zhihu"](https://www.zhihu.com/question/325988088)

will show:

By using the links, we can make the visitor redirect to other pages easily.

How to add tables

Apart from lists and links, we may also want to create tables in our wiki.

The code for a sample table is:

| Head 1        | Head 2        | Head 3        |
| :------------ |:-------------:| -------------:|
| left-aligned  | centered      | right-aligned |
| row 2  col 1  | row 2  col 2  | row 2  col 3  |
| row 3  col 1  | row 3  col 2  | row 2  col 3  |

The table will be:

Head 1 Head 2 Head 3
left-aligned centered right-aligned
row 2 col 1 row 2 col 2 row 2 col 3
row 3 col 1 row 3 col 2 row 2 col 3

How to add images

To make our wiki visual appealing, we may want to add images to our wiki.

Basically, there are two ways to add images. The first one is loading online images directly by using its url. The grammar for this is similar to the links:

![Alt text](image url)

For example:

![Alt text](https://seofiles.s3.amazonaws.com/seo/media/cache/6b/0b/6b0b91e1e3f3cc4c4244d8d5b1740944.jpg)

The image for example code is: Alt text[2]

Please note that the extension of the image url should be a valid image extension (e.g. jpg, jpeg, png...)

The second one is upload your local images to the wiki. It is more complex than the online one, but this way is more stable than previous one because the online url may become invalid somedays.

To achieve it, we should clone the wiki project to our local path first. You can choose any path in your laptop as the source folder for the project. Then open the terminal/command-line in the source folder and type in:

git clone project_url

To clone this wiki:

git clone https://github.com/ZhihengZhou/Software_Engineering_Wiki.wiki.git

You can find your wiki url in your Github wiki page. The url is around the right-bottom of the page.

If your already clone the project to your laptop, you can go the project folder and type in following code in terminal/command-line to update the project:

git pull project_url

To update this wiki:

git pull https://github.com/ZhihengZhou/Software_Engineering_Wiki.wiki.git

After you have the newest version of project in your laptop, you can add images to the project folder. We suggest you to have a folder for images only. In this case, you can create a folder called "images" in your project folder. Then you can move any local image you want to the "images" folder.

After that, we need to push the project back to the Github to upload all the images to your online wiki. By doing this, we should open the terminal/command-line in the project folder and type in:

git add .
git commit -m "Add images"
git push -u origin master

Now, we have uploaded the images into the Github wiki. To add the local images to the wiki, we can just simply use the code:

[your images path](/ZhihengZhou/Software_Engineering_Wiki/wiki/your-images-path)

In this case, the image name is "software_engineering.jpg" and it is in the images folder. Then the code should be

[images/software_engineering.jpg](/ZhihengZhou/Software_Engineering_Wiki/wiki/images/software_engineering.jpg)

The image for example is shown below, which is same to the online example. images/software_engineering.jpg[2]

However, we should obey the following rules for this operation:

  • Please make sure the project is up-to-date before you adding the images to your local project folder.
  • Please do not make any change while someone is uploading the images.

How to add anchor links

When our wiki page is long, it could be difficult for visitor to locate the target section they want. In this case, we may want to add anchor links to the top of our wiki page, which can help visitor to jump to their target section of current wiki page quickly.

Below image shows the anchor link for anchor links of this wiki page: images/anchor.png

If you click one of the anchor link, you may notice that the page will jump to the corresponding section. To achieve this, we can add a "anchor link" at the top of the page at first. Then we can add a kind of "flag" in the middle of the wiki page, which is the position you want the "anchor link" jump to. Normally , the "flag" will be set to the position which is above the target section/topic title.

For the code of the "anchor link":

<a href="#link_name"> Text or description for the link </a>

For the anchor link of this section of this wiki page:

<a href="#anchor"> How to add anchor links </a>

And for the code of the "flag":

<a id="link_name" />

For the flag of this section of this wiki page:

<a id="anchor" />

Please note that the "link_name" should be the same for one pair of "anchor link" and "flag".

Reference

  1. Guides.github.com. 2014. Mastering Markdown ยท Github Guides. [online] Available at https://guides.github.com/features/mastering-markdown/ [Accessed 29 April 2020].
  2. GitHub. 2017. Adam-P/Markdown-Here. [online] Available at: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet [Accessed 29 April 2020].
  3. (2020) [online] Available at: https://www.ozassignments.com/solution/itech7410-software-engineering-methodology-proof-reading-services [Accessed 29 April 2020].