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.
- The Basics
The docs articles are stored as Markdown files under /_articles/. For example, take a look at /_articles/upgrade.md. You can use the GitHub website itself to navigate to, create, edit, and delete pages.
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 support.system76.com/articles/
) with the .md
filetype (i.e. server-setup.md
). Don't use spaces; instead, use dashes (-
). Then include the following (called frontmatter) at the very top of the file (including the ---
es):
---
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.
image: https://system76.com/images/foo.jpg
keywords:
- List
- of
- keywords
- about
- this
- page
- System76
---
A couple of notes:
- The
title
should be phrased so a customer could say, "I want totitle
." For example, useUpgrade Ubuntu
instead ofUpgrading Ubuntu
. - The
image
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
, **bold**
, _italic_
, and other markdown to make the page look awesome.
For keyboard shortcuts, use the HTML tag <kbd>
, i.e. <kbd>Alt</kbd>+<kbd>F4</kbd>
.
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.
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.
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 get into the the Articles section, set section: articles
.
- Files, Images, & Links
To store files (i.e. BIOS updates), put them in the /files
folder. If it's a BIOS/firmware update, it goes in the /files/firmware
folder and should be named like model-version.bio.zip
, i.e. meer1-0358.bio.zip
.
When linking to files or images, prepend the link with {{site.baseurl}}
, i.e. {{site.baseurl}}/files/firmware/meer1-0358.bio.zip
. This will ensure links will continue to work even if we move the docs site elsewhere.
- More advanced stuff
The Ubuntu logo can be included in a doc using the following span:
<span class="fl-ubuntu-inverse"></span>
This is capable of being embedded in other Markdown and Tags, for example, you can create an Ubuntu Key item as follows:
<kbd><span class="fl-ubuntu-inverse"></span></kbd>
If you would like to run a local instance of Jekyll to see changes without uploading to the public website, please run these commands to install Ruby, Nodejs, and Jekyll:
curl -sL https://deb.nodesource.com/setup_7.x | sudo -E bash -
sudo apt install -y nodejs build-essential ruby-full
gem install jekyll
cd docs
jekyll serve
Cassidy will update this with more advanced things later. Until then, ask him directly. ๐