Maintenance and Development
Development Background
We developed this playbook website with the US Web Design System in mind. The site is a clone of the 18F US Web Design Jekyll theme that we modified to fit BC Government branding. The content is hosted on the bcgov collection of repositories.
Some of the changes we made include:
- Replacing all instances of “uswds” to “bcwds”
- Inclusion of the BC Government masthead
- Alteration of the header and footer elements
- Application of the BC Sans font
Resolving and Actioning Issues
When actioning an issue, consider linking your pull request. This not only allows for collaborators to see who is working on what issues, but it also makes it so that the issue is automatically closed when the pull request is merged.
Furthermore, take some time to consider what kind of change you are making. Is it a small change, or a big change? This may determine how you resolve the issue.
Small Changes
If you are just making small changes to a few words in one file (likely a Markdown file), then it would be acceptable and easy to use the GitHub file editor on the bcgov repo. This is not advisable for larger changes, or if you plan on making changes to multiple pages.
Big Changes
You will need a foundational understanding of Git and GitHub concepts, such as repos, commits, and pull requests, for submitting larger contributions.
When you submit a contribution for adding, changing, or removing content you will have to submit a pull request, which will be reviewed.
If you are making big structural or visual changes to the playbook, we suggest that you get set up for local development on your computer. This increases efficiency by allowing you to preview the changes you are making in real time, and it reduces the risk of pushing errors to production.
Follow these steps when making big changes:
- Make a fork of the bcgov repo
- Enable GitHub Pages on the forked repo
- Clone the fork to your local machine
- If you want to preview your changes locally:
- Set up your workstation for Jekyll development
- Familiarize yourself with the structure of the playbook
- Preview your changes with a local server
- Issue the following commands to push the changes to your forked repo:
git add . git commit -m “Meaningful message about your changes” git push origin master - Ensure everything looks good on your forked GitHub Pages site
- Note: the way GitHub Pages compiles your website may differ than what you see during local development.
- Make a pull request
A Note on Versioning
If the changes you are making to the site are quite large, consider creating a new version release. Please consult these resources before creating a new version:
Developing With Jekyll
OS Recommendation
While Jekyll will work on Windows, it is not officially supported by the Jekyll team. If you only have access to Windows, please consider using Windows Subsystem for Linux for development.
Getting Started
To get started developing with Jekyll, use this guide. The terminal will be very helpful if you are missing any packages, so be sure to read any error messages in detail.
A Note on Markdown
The Markdown files that hold the playbook content live in the “plays” and “pages” folders. If you are unfamiliar with Markdown, this is a good place to get started.
Playbook Structure
The playbook follows the general structure of a Jekyll site. If you wish to make large structural or navigational changes, the resources below should help you.
Note: the following list is not exhaustive (as there is a wealth of Jekyll documentation available online), but it should be a good start.