Skip to main content Link Menu Expand (external link) Document Search Copy Copied

Handbook maintenance

On this page

Tech stack

The architecture of the handbook has been kept simple to ease and reduce maintenance. All components are standard, hosted in the cloud and based on GitHub’s free SaaS offering.

  1. GitHub Pages with standard functions for hosting
  2. Jekyll as a static site generator
  3. GitHub Actions built-in Pages action is used to automatically deploy the site once a PR has been merged on the main branch
  4. just-the-docs Jekyll site theme plugin used for branding, mobile view and navigation
  5. Markdown (GitHub flavored) for content

The code is hosted at the /linuxfoundation/devex-and-commsuccess GitHub project, it is open source and public. So is the rendered content on the handbook site. Content that needs to be confidential needs to go in the /linuxfoundation/devex-and-commsuccess-internal repository.

Folder structure

The top level structure is also simple. The most important folder is handbook, where the raw content to be served is stored in a hierarchy of markdown files that mirrors the structure of the navigational panel on the handbook site.

.
├── assets      <= Contains images and other assets to be embedded in the pages
├── _config.yml <= GitHub Pages Jekyll config as per https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll#configuring-jekyll-in-your-github-pages-site
├── _data       <= Contains Jekyll data files to autogenerate content as per https://jekyllrb.com/docs/datafiles/
├── Gemfile     <= Adds required gems to use the standard Jekyll's github-pages plugin
├── handbook    <= Main folder. All markdown files that are part of the handbook (except for the front page on README.md)
├── Makefile    <= Currently unused. It can be used in the future to ease local builds to test content on a local machine
├── README.md   <= Home page of the handbook site and main readme of the project in GitHub
└── _sass       <= Contains SCSS files for a minimal layer of theme customization to add LF branding

Maintenance

The handbook is designed to require little maintenance, as it’s using mostly off-the-shelf hosted infrastructure provided by GitHub. If any additional configuration is required the /_sass (branding), config.yml (plugin and site configuration) and /_data (autogenerated content) are the most likely items to be modified.