by system76

system76 / docs

System76 documentation site

166 Stars 187 Forks Last release: Not found Other 2.0K Commits 0 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

System76 Support Docs

The docs system is powered by GitHub Flavored Markdown. If you don't know what Markdown is (or need a refresher), take a minute to look over the basics.

It is also powered by GitHub itself. If you know how to use git locally with GitHub, feel free to update the docs that way. Otherwise, we'll assume you will be using the GitHub website to update the docs.

1. The Basics

The docs articles are stored as Markdown files under /_articles/. For example, take a look at /_articles/ You can use the GitHub website itself to navigate to, create, edit, and delete pages.

Create an article

To create a new support article, click the + icon at the top of the /_articles/ page.

> docs / _articles / +

Name the file something short but descriptive (this will be the part of the URL after
) with the
filetype (i.e.
). Don't use spaces; instead, use dashes (
). Then include the following (called frontmatter) at the very top of the file (including the
layout: article
title: Do the thing
description: >
  A more descriptive sentence or two about the page; will show up in search engines and on the support home page.
  - List
  - of
  - keywords
  - about
  - this
  - page
  - System76
hidden: true

A couple of notes:

  • The
    is a full URL to an image and will show up on social media, when shared in Slack, etc.

After that, it's just the contents of the article in markdown. Feel free to use

# Heading1
## Heading2
, and other markdown to make the page look awesome.

For keyboard shortcuts, use the HTML tag

, i.e.

The default publication status is set to

, which is hidden. To make your article visible, change this to
. There is no section included by default. To make your article visible within a section, add it.

When you're all done, fill out the "Commit new file" form at the bottom with the description of your changes and press the "Commit changes" button.

Edit an article

To edit or update an article, click on the article's file in GitHub. Then click the pencil "Edit this file" icon on the top-right. You can now edit the contents right on GitHub. To see what it will look like before you save it, click the "Preview changes" tab at the top.

When you're all done, fill out the "Commit changes" form at the bottom with the description of your changes and press the "Commit changes" button.

Index page

Articles will only show up under the section they are configured for. To prevent an article from showing on the index page, set

hidden: true
in its frontmatter. To get it to show up under Frequently Answered Questions, set
section: faq
in its frontmatter. To get it to show up under Known Solutions, set
section: solutions
, and to put it in the Articles section, set
section: articles

2. Files, Images, & Links


To store files (i.e. BIOS updates), put them in the

folder. If it's a BIOS/firmware update, it goes in the
folder and should be named like
, i.e.

Images & Links

When linking to files or images, prepend the link with

, i.e.
. This ensures links continue to work even if we move the docs site elsewhere.

3. More advanced stuff

The Ubuntu logo can be included in a doc using the following span:

You can embed this in other Markdown and Tags, for example, you can create an Ubuntu (Super) key:

Local Development

To run a local copy of the site to see changes without pushing, install Ruby, Nodejs, and Bundler (for more info, see this GitHub Documentation):

curl -sL | sudo -E bash -           # Add stable NodeJS repo
sudo apt install -y build-essential nodejs ruby ruby-dev zlib1g-dev      # Install dev tools, NodeJS, Rudy, and zlib
sudo gem install bundler                                                 # Install Bundler to manage site dependencies
bundle install                                                           # Install gems to run Jekyll

Then run jekyll:

bundle exec jekyll serve # Run Jekyll with Bundler

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.