The Linode Docs currently contain over 1000 articles.
(1027 at the time of me writing this.)
The topics covered include:
Note: and more
Note: Here comes the git.
$ git clone email@example.com:stvnjacobs/docs.git Cloning into 'docs'... remote: Counting objects: 43115, done. remote: Compressing objects: 100% (28/28), done. remote: Total 43115 (delta 25), reused 21 (delta 14), pack-reused 43073 Receiving objects: 100% (43115/43115), 293.67 MiB | 8.74 MiB/s, done. Resolving deltas: 100% (29522/29522), done. Checking out files: 100% (3355/3355), done.
$ cd docs/ $ git remote add upstream firstname.lastname@example.org:Linode/docs.git
This will allow you to pull in changes made to the main repository.
Note: Git is set up to be a distributed system.
GitHub just happens to be the "main source of truth" for Linode's docs repo.
By forking the repository, you have created your own copy, hosted on GitHub.
By cloning your fork, you are replicating that copy to your local computer.
But to make changes to our docs, all changes will need go through the Linode/docs repository.
By adding a "remote", we are letting git know that there is another copy of the repository.
We can pull in any changes that are made this repository.
upstream is only a convention.
You can confirm that
Linode/docs has been linked with the following:
$ git remote -v origin email@example.com:stvnjacobs/docs.git (fetch) origin firstname.lastname@example.org:stvnjacobs/docs.git (push) upstream email@example.com:Linode/docs.git (fetch) upstream firstname.lastname@example.org:Linode/docs.git (push) $ git pull upstream master
@1 @[2-5] @7
Unless someone made a change in the last few minutes, since you configured the remote, the
git pull upstream master should return
Already up to date..
$ git branch * master $ git fetch upstream $ git branch -a * master remotes/origin/HEAD -> origin/master remotes/origin/config/smart-fractions remotes/origin/fix/postgres-pgadmin-link remotes/origin/master remotes/upstream/cwlinode-patch-1 remotes/upstream/freebsd_minecraft remotes/upstream/install-nginx-ubuntu remotes/upstream/master remotes/upstream/migrate remotes/upstream/nginx-basic-graphic
@ @ @ @ @ @[8-11] @[12-17]
./ ├── themes/ ├── README.md ├── netlify.toml ├── docs/ ├── CONTRIBUTING.md ├── config.toml ├── CODE_OF_CONDUCT.md ├── ci/ ├── archetypes/ ├── .vale.ini ├── .travis.yml ├── .gitignore └── .git/
@ @ @
If you are creating a new doc, or editing an existing one, this is where you will be working from.
Note: Open the GitHub link and show the docs folder
We are jumping to archetypes, and skipping CI. We have to write a post first.
Hugo has what they call archetypes.
They are pre-formatted templates for various kinds of posts.
archetypes/ ├── default.md └── content.md
Note: We only write docs, so there isn't much variation, here.
What it gives us, though, is uniformity.
It also let's us set a standard for what metadata is required for new docs.
Show the frontmatter
author: name: Linode email: email@example.com keywords: ["getting started", "intro", "basics", "first steps"] description: 'This guide will help you set up your first Linode.' og_description: "Learn how to create an account, boot your first Linode, and connect via SSH with our Getting Started guide." license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' modified: 2018-05-23 modified_by: name: Linode published: 2009-07-19 title: Getting Started with Linode show_on_frontpage: true title_short: "Getting Started" weight: 10 icon: "book" show_on_rss_feed: false
Note: Not pictured
Hugo, and therefore the Linode Docs, render pages from Markdown.
Hugo allows for templating of Markdown documents.
One example, used throughout our documentation, are Shortcodes.
$ brew install hugo
$ cd docs/ $ hugo server
There are many reasons to fix a guide:
For larger changes, it is best to open an issue on the GitHub project.
You can still make the changes, but it is best to reach a consensus with the Docs team before putting in the effort to rewrite a large portion of a doc.
It is best practice to make changes on a new branch.
This is more for your own good, as it allows you to keep your master in sync with upstream, while you work on one or more of your own branches.
$ git checkout -b fix/remove-debian7 # fix fix fix $ git push origin fix/remove-debian7
$ git checkout master $ git checkout -b doc/troubleshooting-ssh $ hugo new --kind content troubleshooting/troubleshooting-failing-ssh-connections/index.md
archetypes/ ├── default.md └── content.md
The Linode Docs have a test suite that is run as part of a continuous integration pipeline. It test for thing such as:
$ cd ci/ $ virtualenv -p python3 .env $ source .env/bin/activate $ pip install -r requirements.txt
@ @3-4 @
We need two terminals open, so open up a second.
Navigate to the root of the docs directory in both terminals.
$ hugo server
$ ./ci/scripts/blueberry.sh $ ./ci/scripts/docs404.sh $ ./ci/scripts/vale.sh