Skip to main content

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:

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.

Before proceeding read this page.

Follow these steps when making big changes:

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.





Back to the Top