This page contains the documentation for keeping our documentation updated.
Webdocs is built out of a collection of text files hosted on GitHub. To update this site, clone and edit the files in the
docs/ folder. Once your addition is ready for publishing, push to the master branch, and the site will automatically update after a few minutes.
For easy development and parsing, webdocs uses the liquid parser. This allows for the use of variables and other bits of code to be written directly into our documents. The way out site is set up, every file must start with a liquid header. Note, this must literally be the first thing in the file, line 1 cannot be blank.
Here is a standard header for this page
--- layout: default title: "Meta" nav_order: 12 permalink: /docs/meta authors: ['ewpratten'] ---
The start and end of a header are defined by three dashes.
The layout must be
default. Title is what shows in the navigation bar, and permalink is the url for this page. Change these to match the page you are writing. The
nav_order variable is the order this item appears in the navigation bar. Generally, put new pages at the bottom of the list.
To create a folder in the nav bar, create a folder inside of the
docs/ folder, and make a file with the same name inside that folder. This file acts at the table of contents for that folder, and must have an extra line in it’s header:
--- # <The rest of the header goes here> has_children: true ---
To add children to this sub-section, add new files to it’s folder, and give them this extra attribute:
--- # <The rest of the header goes here> parent: "<Title of the index file>" ---
The parent must exactly match the title of the index (table of contents) file for that folder.
Every file also has an
authors tag in it’s header. This is used to keep track of who has worked on each file. To add yourself as an author to the page, add your GitHub username (all lowercase) to the list.
--- # Example of only one author authors: ['slownie'] # Example of two authors authors: ['retrax24', 'ewpratten'] ---
This list will be displayed at the bottom of the page.
The way our contributors list is set up allows for automatically generated profile pages for each member (currently disabled). These pages include the member’s name, some information about what they do, and their github account details. This is all configured through the
Here is an example entry for one of our graduated members, Matthew Eppel.
faceincake: name: Matthew Eppel is_lead: false is_mentor: false github: faceincake
These variables should be pretty self-explanatory. The key must be the same as the value of
To add a new member to the website, add them to this list.
Webdocs is hosted on GitHub pages and automatically updated by a CD pipeline. This is all automatically configured.
The backend of webdocs is Jekyll. This tool turns some markdown and html into a nice website, automatically. For anyone looking to make majour changes to this site, or the programming homepage, you will need to know how to use Jekyll. Luckily, the Jekyll Docs have everything you need to know for this job.
We are using a modified version of Just the Docs. Their website has some useful information on how to use their theme-specific tools.
We have a few plugins installed for this website. They are:
Jekyll-feed automatically generates an RSS feed for this website.
Jekyll-redirect-from allows us to set up link shorteners and redirects.
jemoji enables slack-like emoji. (That was done by adding
:tada: to the file)
Jekyll-mentions allows us to automatically link to any github account. @frc5024 (That was done by adding
@frc5024 to the file)
Jekyll-seo-tag automatically handles Search Engine Optimization for this site.
The programming team has two different websites.
Second, is webdocs, which is hosted in the webdocs repo.
For instructions on updating the homepage, take a look at it’s repo’s README.md file.
To run a development version of this site locally,
- Install Ruby
- Install Jekyll with:
gem install jekyll bundler
- Then run
bundle exec jekyll servein the root of this project
- The site is now live at localhost:4000