Skip to content

How to create and edit a GitHub Wiki

Jump to bottom Edit New page
Bernardo edited this page Apr 30, 2020 · 7 revisions

Before we start, we would like to say that this tutorial is based on the GitHub markdown guides[1] and adam-p/markdown-here[2]. We strongly recommend you to visit these pages for more information. Please, feel free to add new information here if you find it useful!

In this page, we will talk about how to create a GitHub page and how to edit it. Below you will find the list of topics addressed in this tutorial:

How to create, edit, and add new GitHub Wiki page

  1. Create a new GitHub project on your GitHub account
  2. Go to the project repository you have just created
  3. Click on the "Wiki" tab that can be found in the menu bar
  4. Now, click on the "Create the First Page" button

Check the image below:

After clicking on the "Create the First Page" button, you will see the following page (a page that you can edit):

In the editing page, use the first input text field to add a title to your page. Add the main content in the second text area (the largest one). Note that this Wiki page use Markdown edit mode. After you finish editing, select the preview tab to view how your wiki page looks like.

The "edit message" text field is used to add comments related to the edits you made to the page. Although it is optional, we highly recommend you to specify the changes made. As this is a collaborative Wiki, it is always good to know what was added/changed/removed and its reasons.

If you are satisfied with the appearance of your page, press the "Save Page" button. You may see something like the image below.

Congrats! You have just created your home/main page of your Wiki. Click on the "Edit" button to edit your home page or click on the "New Page" button to create a new Wiki page. The process to create and edit new pages are the same.

How to add topics/sections

This is very easy! After creating a Wiki page, you can add some topics/sections to your Wiki. A topic/section is called here as Headings.

As in the HTML markup language, the headings size range from H1 (largest) to H6 (smallest). Here, the size of the headings is specified by the number of hashtags (#) used, e.g, "#" is equivalent to the H1 html tag and "######" is equivalent to the H6 tag.

For example, the following code:

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

may result in the following sections/topics:

Title H1

Title H2

Title H3

Title H4

Title H5
Title H6

Note that since there is a horizontal rule (line) after headings H1 "#" and H2 "##", we recommend you to use H1 and H2 for your main topic/section titles.

How to create ordered and unordered lists

There are two types of lists using the Markdown editing mode:

  • The ordered list (1, 2, 3...N). It is often used when the items described follows a specific order.
  • And, the unordered list (bullet list). It is often used when the items described does not follow a specific order or are equally important.

The code for the two lists is presented below:

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

Unordered list:
* Item
* Item
* Item

This codes will generate the following output:

Ordered list:

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

Unordered list:

  • Item
  • Item
  • Item

How to create internal and external links

Wikis may have two different types of links:

  • Internal links: Links that point to other pages within your Wiki; and,
  • External links: Links that point to external pages, e.g., another Web site (e.g. Baidu, Wikipedia).

To create an internal link, it is necessary to specify it in two parts:

[title/description of the link](relative path for the internal link)

For example, in this Wiki, we have at least these two other pages: "Home.md" and "The-Australian-National-University.md". Thus, to create a link to them, we need to write the following code:

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

The output of this code is:

To create an external link, use the absolute URL address. For example:

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

The output will be:

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/bernardopnunes/SoftwareEngineeringSDUW.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/bernardopnunes/SoftwareEngineeringSDUW.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]]

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]]

The image for example is shown below, which is same to the online example. [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:

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].

git clone https://github.com/bernardopnunes/SoftwareEngineeringSDUW.wiki.git

Add a custom sidebar

Clone this wiki locally