System76 support documentation site
The docs system is powered by NuxtJS with @nuxtjs/content,
tailwindcss, and some other packages. It uses Markdown in the /content/
folder to render every article. If you don’t know what Markdown is (or need a
refresher), take a minute to look over the basics.
All articles are stored as Markdown files under /content/. For example,
take a look at the /content/upgrade-pop.md file.
To create a new support article, click the + icon at the top of the
/content/ page.
Name the file something short but descriptive. This will be part of the URL, for
example server-setup.md will become
https://support.system76.com/articles/server-setup. Don’t use spaces; instead,
use dashes (-).
Then include the following text at the very top of the file (including the
---es).
---
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.
keywords:
- List
- of
- keywords
- about
- this
- page
- System76
facebookImage: /_social/article
twitterImage: /_social/article
hidden: true
section:
---
A couple of notes:
After the --- line, you can type 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>.
The default publication status is set to hidden: true. To make your article
visible, change the hidden: true to hidden: false in the top of the file.
To make your article visible within a section, write the section name in the
section: line. For instance, to add an article to the “Switching to Linux”
section, the line should be section: switching.
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. If you
set hidden: true in an article, it will not be visible on any of the index
pages, and you will need to know the direct URL to view it.
If you want an article to not show up on the index page, but be visible
on /articles, set hidden: false and remove the section: line from the
article.
To get an article to show up under Frequently Answered Questions, set
section: faq.
To get an article to show up under Known Solutions, set
section: solutions.
To get an article to show up under Articles, set section: articles.
To store files (i.e. BIOS updates), put them in the /static/files folder. If
it’s a BIOS/fireware update, it goes in the /static/files/firmware folder and
should be named like model-version.bio.zip, i.e. meer1-0358.bio.zip.
Anything in the static/ folder will be available at the base URL. For
instance, /static/files/firmware/meer1-0358.bio.zip will be downloadable at
https://support.system76.com/files/firmware/meer1-0358.bio.zip.
When linking to files, please use the absolute path, i.e.
/files/firmware/meer1-0358.bio.zip.
The Ubuntu logo can be included in a doc using the following HTML tag:
<font-awesome-icon :icon="['fab', 'ubuntu']"></font-awesome-icon>
You can embed this in other Markdown and Tags, for example, you can create an
Pop!_OS (Super) key:
<kbd>
<font-awesome-icon :icon="['fab', 'pop-os']"></font-awesome-icon>
</kbd>
This site is built with NuxtJS and @nuxtjs/content. To get started,
you will need to clone this repository to your local computer.
Next, you will need to setup node 14 <= and npm. The nodejs website
has great documentation on how to do this.
After that, you can run npm ci to install the needed packages, and npm start
to start the development site. You will then see a Listening: http://localhost:3000/ line in your console showing where you can access the
development site.
To deploy changes, simply make a PR to the system76/docs GitHub
repository and once it’s merged, it will be deployed to the live site!