GitHub Pages

The bc-vcpedia content is additionally hosted on a GitHub Pages deployment.

This can be found at https://bcgov.github.io/bc-vcpedia/

Templating

The site uses a remote theme. So no manual Jekyll and Ruby setup (Gemfiles etc) is needed to be contained in this documentation repo. If much more complicated structure or customization is needed it could be hosted as a full Jekyll setup rather than a remote theme.

See theming and any Jekyll details in the repo's _config.yml

The theme is a free 3rd party theme called Just the Docs (https://just-the-docs.com/). It provides some very useful features along with the styling including

• Site-wide seach
• Auto-generated navigation and tables of contents
• Responsive design for mobile/etc

Publishing Source

As this isn't a traditional code repo with a separate documentation structure and site (the contents of the repo are the documentation to view on the GH Pages site) we keep the GH Pages up to date along side of the site, and don't reproduce the content in a separate directory or structure.

So it's not appropriate to use a docs folder (the docs are the root) or anything.

The publishing is done from main rather than a separate gh-pages or docs branch, as any changes to main content should be reflected in the deployed page.

See Settings > Pages > Branch if any of this needs to be altered.

Editing

Most of the work here is being done by the actual Markdown file contents, as they are the authoritative source of the site contents. Adding any content generation via other means for the GH Pages site (via Jekyll) might not be a good idea, as that generation would only create resultant html for the GH Pages site. It wouldn't dynamically generate markdown source, so anyone else ingesting these markdown files or reading them on GitHub would see the Jekyll code rather than the documentation contents.

At this time, the only Jekyll front matter affecting display is the page Titles for Navigation. To alter those titles or any navigation structure (like ordering) alter the front matter on each desired Markdown file.

More customization specific to the rendered site could be done, for example CSS overrides to style things. See Customization below.

Customization

See https://just-the-docs.com/docs/customization/ for further customization options if needed.

See Jekyll docs for Jekyll syntax and features.

Previewing

As the GH Pages site is meant to render the approved documentation that is accepted and completed, it will render the main branch contents. So you would not see your changes until merging in.

This should normally suffice as the markdown files themselves can be reviewed in a pull request on their own.

A branch or Pull Request can't be previewed with the rendered site in the repo, but to easily try out changes if you are making larger changes to the actual Jekyll site itself you can

• Fork the repo
• Make a branch on your fork
• On your fork set up a GH Pages deployment pointing at your forked branch
• PR the changes back to the upstream repo after previewing

Future Considerations/Notes

• Added a few lines of front matter yml to each md file for Jekyll to pick up better navigation titles and organization. This means you see that front matter when looking at the file on Github, as it's part of the codebase. Not sure if this could be any issues with any future intent on sites ingesting these md files (any machine readable governance or anything). They would probably be parsing things out anyways.
• The remote theme is just set to remote_theme: just-the-docs/just-the-docs but could be pinned to a specific version (for example remote_theme: just-the-docs/just-the-docs@1.0.1 if avoiding changes to the linked theme is needed.