Contributing to the Wiki

Hello! Would you like to create an article for this wiki or want to modify something? Here’s how to contribute!

Requires some knowledge of Markdown. See @adam-p’s cheatsheet here. This article will also only cover how to style them properly, so read other articles in this wiki to get a feel of how to structure your article.

If you want to see the docs for our theme (Just the Docs), click here.

Already read this but don’t know where to start? Check the issues page for the repository!

Table of Contents

Creating the File

Fork the wiki’s repository, clone your fork to your computer, and go to the repo folder.

Create your Markdown file (.md) in the respective category in docs/.

docs/guides/ contain various step-by-step guides for the user to follow.

docs/factoids/ contain the articles that are either copied from, or linked to by embeds.

docs/learning/ contains education articles like Computing 101

Testing Locally

You can host the wiki locally to check what your articles will look like:

  1. Ensure you have ruby and gem installed. Run the following commands in the folder containing Gemfile:
  2. gem install jekyll bundler
  3. bundle install
  4. bundle exec jekyll serve
  5. The site should be hosted at: http://localhost:4000/

After doing step 3, you can just skip to step 4 if you want to test the site again.

Creating the Pull Request

Once your changes are complete you can open a pull request (PR) to the master branch.

FrontMatter Header

The FrontMatter Header contains all of the metadata of the page, including title, parent category, and date of last modification. This is required and should always be placed on the first line of the file.

Here is the header for this specific page:

---
layout: default
title: Contributing to the Wiki
nav_exclude: false
has_children: false
parent: Information
search_exclude: false
last_modified_date: 2023-02-04
---

The important things for you to look at are title: and parent:

The title contains the name that will be displayed for the page on the sidebar. The parent assigns the page’s category in that sidebar.

You can copy the codeblock above to your markdown file and replace all the fields.

Page Headers

For the sake of consistency across the pages:

Headers like these are for the for the main title of the page

# Headers like these are for the for the main title of the page

These should be used for different sections of the page

## These should be used for different sections of the page

Always arrange headers in order

### Always arrange headers in order

Like so.

#### Like so.

Table of Contents

To add a table of contents to your page, add this AFTER your first header (usually the title):

Table of Contents Code

This will output a table of contents that looks like what this page has. If you would like a numbered table of contents, replace toc.md with toc_numbered.md

Add {: .no_toc } below a heading if you do not want that heading to be included in the Table of Contents.

# Contributing to the Wiki
{: .no_toc }

Images

To add a custom image, place your image in /assets/<page-name>/<image.png>, and link to it like:

![![Table of Contents Code](/assets/writing-articles/toc1.png)]

(see Table of Contents above for a live example.)

Page Styling

Bolding and Italicizing

Bold (**Bold**) important words/phrases and Italicize (*Italicize*) them to emphasize like:

Applications you have installed, regardless of which drive you have installed it on, will not carry over the next time you clean install Windows, even if it is on a different hard drive to your Windows drive. (source)

Callouts

Callouts are used to “call out” specific information. We have a number of these at our disposal and their paradigms are outlined below. Please adhere to this paradigm for consistency.

The format to create a callout is below. You can add additonal “quote” > lines without issue. Use blank quote lines for spacing.

{: .warning .warning-icon }
> It is very important that you remember to **power-off the motherboard** and switch-off and unplug the PSU after each component test. Do this before you remove or install anything.

The colours used for callouts are defined in setup.scss and you must also define them in config.yml. The icon names come from Font Awesome, but they are defined in custom.scss.

Danger

Danger block

Use {: .danger .danger-icon } for danger blocks

Danger boxes contain critical information that, if dismissed, will lead to operational or security issues!

Data deletion callouts should be Danger callouts!

Warnings

Warning block

Use {: .warning .warning-icon } for warning blocks

Warning boxes contain information that may lead to issues and should not be quickly dismissed.

Caution

Caution block

Use {: .caution .caution-icon } for caution blocks

These have no documented use.

Information

Info block

Use {: .info .info-icon } for info blocks

Info boxes contain notes or helpful hints that may be safely ignored.

Success

Success block

Use {: .success .success-icon } for succes blocks

Success boxes contain a positive result, if you do not see this result something has gone wrong.

You can link to headers in the current page with:

[Page Header](#page-header)

Page Header

and to other pages with

[BSOD Article](/docs/factoids/bsod)

BSOD Article

Collapsible Sections

If you want the content to be collapsible, add:

<details markdown="1">

    <summary>The Title</summary>

    The Content

</details>

<summary>The Title</summary>

The Content