Cloning a Wiki simply means copying the Wiki to a local machine where it can be edited in a text editor (Visual Studio Code for example, this is the editor of choice and interfaces with GitHub allowing all the version control tools for a repository to be accessed locally on a PC) that usually offers more facilities than the basic GitHub web-based editor. Changes made on the local machine can be “pushed” back to GitHub where they will appear within the Wiki.

⬆️ Top

---

Unless your Wiki is very short and simple, you will almost certainly want to clone it to your local machine.

The GitHub Wiki editor is rudimentary and has only basic editing facilities. It cannot search and replace in multiple files; it does not have syntax highlighting^💠1 and it does not allow folder structures to be created. A fully fledged text editor such as VS Code has all these things. Text editors generally have flexible preview facilities, proper search and replace (within and across multiple files), file and folder management, they also (usually) have some form of extensions that can be incorporated to give additional facilities (version control interfaces, image file previews &c.).

Life is much easier using a proper text editor rather than the GitHub editor.

That said, it is not the main reason for cloning a Wiki:

The main reason for cloning a Wiki to a local machine is it allows a folder structure to be applied to the Wiki.

This is essential for what we will do later on (it allows different sidebars and footers for each Wiki page).

⬆️ Top

---

The Wiki repository can be “cloned” (copied) locally to a PC using the ${\large \color{#00B050}\langle\text{clone\ this\ wiki\ locally}\rangle}$ link on any Wiki page:

Figure 2.1 — Clone a local copy of a Wiki

Clicking the link copies the wiki link to the clipboard, in the case of this Wiki it is:

   https://github.com/practicalseries/GitHub-Wiki-Design-and-Implementation.wiki.git

❶	Open a new VS Code window and do the following:
❷	Select ${\large \color{#00B050}\langle\text{Source\ Control}\rangle}$ (in the left bar), ${\large \color{#00B050}\text{Ctrl+Shift+G}}$
❸	Select ${\large \color{#00B050}\langle\text{Clone\ Repository}\rangle}$
❹	Paste the link above into the editor as shown below:
❺	Hit enter and when prompted select a repository location on the local machine (this was mine): Only select the parent directory, VS Code will create the subdirectory that contains the Wiki. It will have the same name as the repository with which the Wiki is associated with .WIKI at the end (spaces in the name will be replaced by dashes).
❻	At the next prompt, open the repository, it looks like this:
❼	This is the cloned repository on a local machine, in Windows File Explorer it looks like this:
	List 2.1 — Cloning a Wiki

In the image above it is possible to see the .git folder, this is the standard folder for a Git repository, it was created by GitHub when we created the first Wiki page

The Wiki is indeed its own repository.

⬆️ Top

---

Cloning a Wiki onto a local machine, provides a copy of the Wiki on that machine. This can now be locally edited and modified as required.

At some point, those modified (or new/deleted) files must be sent back to GitHub so that it can be displayed when the Wiki button is pressed. So how is this done?

The first thing is you must have a GitHub account that has access to the parent repository. In this instance, I’m assuming you have a GitHub account (you wouldn’t be able to create a repository without one) and I’m also assuming that the Wiki in question is one you have created in your own repository (or in a repository to which you have full read/write permissions).

I will take you through this from the point of view of using VS Code as your text editor and that you are not signed into any accounts via VS Code (if it is a clean install of VS Code, you won’t be signed into anything). I’m also assuming that Git has been installed on your machine.

Before we start, there is something irritating that must be done before we can change things and send stuff back to GitHub.

We must first record our GitHub username and email address in Git. See below:

⬆️ Top

---

This is a bit convoluted and it is a requirement of the Git version control system (installed on your PC) and has nothing at all to do with GitHub.

Git won’t allow changes to be committed to a repository (and at this point it is the Git application on your local PC that is in control of the local repository, VS Code is just a wrapper that interfaces with Git) without it having a username and email address for the user making the changes.

Now, Git is horrible. It is a command line interface with absolutely no redeeming features. No one likes to use it, but in this instance, we have to give it some information and this can be done through the VS Code terminal.

In VS Code, select ${\large \color{#00B050}\langle\text{Terminal}\rangle}$ in the menu bar, select ${\large \color{#00B050}\langle\text{New\ terminal}\rangle}$ and the terminal window will open at the bottom-right:

Figure 2.2 — VS Code terminal

Next, we have to issue two commands to Git using the peculiar terminology common to it.

First, we must give it a user name (this should be the same as the username for your GitHub account), the command is (the quotation marks are necessary):

   git config --global user.name "[UserName]"

In my case my username is mgledhill so I enter:

   git config --global user.name "mgledhill"

Next, it needs an email address (any will do, nothing will ever check it), the command is

   git config --global user.email "[EmailAddress]"

In my case my email is [email protected] so I enter:

   git config --global user.email "[email protected]"

In both cases, you will get no response from Git (no news is good news with Git).

In my case it all looks like this:

Figure 2.3 — Git username and email

That’s it, the credentials have been entered (I wish VS Code would find a way around this, it’s a pain in the arse). If you don’t do this, you will get an error message when you try to synchronise the Wiki with GitHub.

⬆️ Top

---

Having cloned the repository (see the previous section), there is a copy of it on the local machine. At this point I’m assuming it is just the Home page created in Section 1.3.1, it looks like this in VS Code:

Figure 2.4 — The cloned Home page in VS Code

It just has one line in it.

Change the text in the line as follows, point ①:

Figure 2.5 — Modified Home page

VS Code detects this change and indicates it as the number 1 over the Source Control icon, point ② .

Click ${\large \color{#00B050}\langle\text{Source\ Control}\rangle}$ and it shows the status of the modified files in the repository:

Figure 2.6 — Changed files

The Home page is showing as a changed file. Before the changes can be added to the re-pository, it must be “staged” (Git terminology for marking a file as ready to be added to the repository). To stage the file, click the ${\large \color{#00B050}\langle\text{plus sign}\rangle}$ in the changes area (highlighted above). It now looks like this:

Figure 2.7 — Staged files

The file is now staged and ready to be “committed” (this means stored in the repository, this is the same as ${\large \color{#00B050}\langle\text{Saving}\rangle}$ the Wiki page in GitHub).

⬆️ Top

---

The modified files can now be committed to the local repository.

To do this, enter a message in the box above the blue ${\large \color{#00B050}\langle\text{Commit}\rangle}$ button (it can be anything you like) and then press ${\large \color{#00B050}\langle\text{Commit}\rangle}$:

Figure 2.8 — Commit the change

VS Code will now ask you to synchronise the files with GitHub (this is called a “push” or “pushing” in GitHub terminology):

Figure 2.9 — Synchronise the change

Figure 2.10 — Username and email configuration error

When you try to do this for the first time, you will be prompted to login to GitHub to verify your status (again you will only have to do this once).

Click the ${\large \color{#00B050}\langle\text{Sync\ changes}\rangle}$ button.

This will open a window asking you to sign in to GitHub:

Figure 2.11 — GitHub prompt to sign in

Click ${\large \color{#00B050}\langle\text{Sign\ in\ wit\ your\ browser}\rangle}$ (unless you have a code). This opens the GitHub sign in screen, enter your credentials:

Figure 2.12 — GitHub prompt to sign in

You can use a passkey if you have one set up, otherwise it will text a code to your mobile phone. Enter your details and click ${\large \color{#00B050}\langle\text{Sign\ in}\rangle}$: and enter the authorisation code that has been sent to you:

Figure 2.13 — GitHub authorisation code

That’s it, you can now close the browser and VS Code will sync the changes.

If you now open the Wiki in a browser, you will see the changes. It looks like this:

Figure 2.14 — Modified page on GitHub

And that’s it. Local changes pushed to GitHub.

---

Footnotes:     

---