Writing Component Documentation
Component design documentation is currently generated and hosted through Github Pages. In order to write documentation for a new component or update existing documentation you’ll need to install some command line utilities and become familiar with the basics of contributing to a git repository. Here are a couple of screencasts that will get you up and running even without previous experience.
Getting Started
This video will walk you through the process of installing all the software necessary to create your own component documentation page. Note that you will need sudo access to complete these steps. You can test for sudo access by opening the terminal application and running this command:
sudo -v
If you get an error message saying that you are not in the sudoers file then you will need to contact your IT group to gain access.
For reference:
- Download Github Desktop
- Clone the design site repository
- Make sure you have at least Ruby v2.0.0 by running
ruby --version
at the terminal - Install bundler by running
gem install bundler
. You will probably need sudo access for this. You may also need to install the command line tools by runningxcode-select --install
. - Install all the software needed to generate the site by running
gem install
from within the repository you downloaded. - Review the Markdown syntax guide
- Download the Atom text editor
- Start Jekyll running by following these steps:
- Right click the ‘design’ repository in the sidebar of Github Desktop and choose ‘Open in Terminal’
- Run this command:
bundle exec jekyll serve --safe
Creating Your First Component
Once you’ve installed the Github pages software you can start your own component documentation page. This video walks through that process: