How to create and edit a GitHub Wiki - bernardopnunes/SoftwareEngineeringSDUW GitHub Wiki

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 a new GitHub Wiki page
  • How to add a topic/section title
  • How to create ordered and 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

  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:

images/create_wiki.png

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

images/edit_page.png

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.

images/edit_and_new_page.png

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

Besides lists and links, you 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 output 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

Basically, there are two ways to add images to your Wiki. The first is using the image URL. For example:

![Alt text](image url)

Or, more specifically:

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

The output for the code above will be: Alt text[2]

Note that the file extension must be a valid one such as jpg, jpeg, png.

You can also upload your local images to your Wiki. It is a bit more complex than the first method, but safer as the image will be hosted on your Wiki and not on someone's else Web site (if they delete, the image will no longer be shown on your Wiki).

To upload an image, you must clone the Wiki project to your local computer first. You can choose any path in your computer as the source folder for your project. After that, 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 on the right side of the Wiki's page.

After cloning the project to your computer, you can go to the project folder, and type the following command in the terminal/command-line, to update your project:

git pull project_url

If you are working with the course's Wiki, use the following command (be careful and be sure you are doing the right thing!):

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

After that, you will have the newest version of the project in your computer, you can add images to the project folder. We recommend you to create a folder specific for images (it will help to organize the files). For example, 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.

Good! Now, 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 the following command:

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 following command:

[your images path](/bernardopnunes/SoftwareEngineeringSDUW/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](/bernardopnunes/SoftwareEngineeringSDUW/wiki/images/software_engineering.jpg)

The image shown below is the same as the one used in the online example. 600px[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 changes while someone is uploading images.

How to add anchor links

When our Wiki page is long, it can be difficult for a user to locate a section within a page. To help users find a specific section, we often use anchor links.

The image below illustrates the use of anchor links: width=420px

If you click on one of the anchor links, the page will scroll to the corresponding section.

How to do it? For this, we need to create an "anchor link". And, also create an anchor where the anchor link will point to.

Code for "anchor links":

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

Code for the anchor:

<a id="link_name" />

For the anchor of this section of this Wiki page:

<a id="anchor" />

Note that the "link_name" should be the same for both "anchor link" and "anchor". This is how they link one to the other.

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