How to add and edit pages on the wiki

Editing and Adding to the Wiki

The wiki is actually just a git repository of markdown files and images that you can clone. This means that everything that can be done with a normal git repo can be done with the wiki, like pushing and pulling, and editing files on your local repo. It is a completely separate repo from the hyped-2021 repo, meaning no files are shared or anything.

You can clone it locally by running

$ git clone https://github.com/Hyp-ed/hyped-2022.wiki.git

All text wiki files must be in markdown! Other supported markup formats like Textile work too, but markdown is widely used and what people typically are comfortable with. PDFs cannot be uploaded to the wiki (not a supported format and PDF's cannot be edited easily anyways). Images can be uploaded to the wiki to be displayed in markdown files, there is a section below going into more detail.

Wiki repository structure

Note that although the wiki is just a regular git repo, and thus has normal directories like you would find in any other repo, directory structure does not impact how wiki pages are displayed. No matter how wiki markdown files are organized in directories, it is totally irrelevant and GitHub will simply display all markdown files it finds as one long list of pages, as shown in the screenshot.

Directories are good, however, for maintaining general organization within the wiki repo. Do use them if you feel it would aid organization, but remember this has zero impact on how they are displayed on the wiki. There is a directory called images, in which all images should be stored. Directory structure within the images directory does not matter, just keep it organized. This directory can only be seen and updated if you clone the repo (GitHub only displays markdown files on the web interface). Do not delete the images directory. More detail on adding images and using them in markdown wiki pages is in the relevant section below.

The sidebar, on the other hand, gives the illusion of a directory like structure in the repo. It is actually just another markdown file, named _Sidebar.md, which contains an indented list of text or links to other wiki pages. These are just links, so they can actually link to other webpages as well, not just our wiki markdown pages.

It is required that you update the sidebar whenever you add or remove (or just want to change it's location in the sidebar) a wiki page. The sidebar is how we intend for wiki pages to be displayed and discovered. Unfortunately this is not an automated process, and must be done manually (explained in a section further below).

Adding pages

When on the web interface, simply click the big green button that says New Page in the top right (didn't include a screenshot since the button is everywhere and easy to find). You can of course also just create a new markdown file in your local repo, commit it, and then push that. As mentioned above, feel free to organize your markdown files in a way that would benefit the organization of the repo, but this will not have an effect on presentation. You must manually add a link to your new page to the sidebar, explained below.

Removing pages

When on the web interface, navigate to the wiki page you want to delete. Click on the Edit button next to the New Page button in the top right. Now simply click the Delete button, again in the top right. You can also of course just remove the file in your local repo, commit the change, and then push that. Obviously please do not delete other people's wiki pages. You must manually remove the link to the deleted page in the sidebar, explained below.

Editing pages

When on the web interface, navigate to the wiki page you want to edit. Click on the Edit button next to the New Page button in the top right. You can also just edit the markdown file in your local repo, commit the changes, and then push that. The sidebar does not need to be updated, unless you want to change the location of the page within the sidebar, in which case read the sidebar section below.

Updating the sidebar

This is important. As explained earlier, the sidebar is simply a markdown file, named _Sidebar.md, containing an indented list of links. These links are primarily links to our own wiki pages, but can be to other webpages as well. Whenever you add/delete/ or change the location of a page within the sidebar, you must manually update _Sidebar.md. This can be done either in your cloned repo of the wiki, or by clicking the little edit button when you hover over the sidebar in the web interface. It is a simple indented list (indents are two spaces), structured like so:

* [Name of link](url goes here)
* [Root level of sidebar](url goes here)
  * [An indented link](url goes here)
  * [Use two spaces for indents](url goes here)
* Can also just be text, doesn't have to be a link!

Note that since you need a url, if you add a new page, you can only really add it to the sidebar once you publish the page and get the url to it. When you delete a page though, you can delete the markdown file and delete the link from the sidebar file in the same step.

Adding images

Since the wiki is just a git repo, we keep all of our images that our wiki markdown pages use inside of the images directory. Within this directory, feel free to create further directories to keep stuff organized, but note this does not have any effect on presentation; it is purely for organization. Note that all of this must be done in a local clone of the repo, since there is no web interface equivalent.

To use an image in a wiki page, simply move your image file somewhere in the images directory, and use the following markdown to display it:

[[/images/path/to/image.jpg | height = 200px]]

You can specify the height of the image, and the width will also be automatically adjusted to scale.

Please do not go crazy on the amount of images you use, since they are quite large files and slow down cloning and pulling of the wiki repo (important when on the beaglebone). If you no longer display your image in a wiki page or simply removed the entire wiki page, remember to remove the respective image file! This is done by simply removing the image file, committing the change, and pushing as usual.