trickstercache.org

This repository contains the documentation site for Trickster, available at https://trickstercache.org.

Making a contribution

To make a contribution to the documentation, file an issue or fork the project and submit a Pull Request. For specific instructions see About Forks and Creating a Pull Request in the GitHub documentation.

Note that the actual documentation content is synced from the main Trickster repo's 'docs' directory. So if you want to fix something in the actual documentation, contribute that to the main repo. Contributions to this repo should be about the actual Docs site (CSS/styling/layout, deployment automation, etc.) rather than its content.

Releases and deployment

The site is published to Netlify by the Deploy to Netlify GitHub Actions workflow whenever a semantic version tag (vX.Y.Z, optionally with a pre-release suffix such as v2.1.0-beta1) is pushed to this repository. Tag this repo with the same version as the Trickster release being documented:

git tag v2.1.0
git push origin v2.1.0

The workflow then:

1. checks out that tag of this repository;
2. runs scripts/sync-docs.sh v2.1.0, which syncs the docs from the same tag of the trickster repo, so the published site always matches that release's documentation, and records the version in data/trickster.toml;
3. builds the site with Hugo, rendering the version next to the logo in the site header so readers can tell which documentation version they are looking at; and
4. publishes the result to Netlify's production site.

An already-tagged version can be re-deployed with the workflow's Run workflow button in the GitHub Actions tab.

One-time setup

• Add two repository secrets under GitHub Settings → Secrets and variables → Actions:
  • NETLIFY_AUTH_TOKEN: a Netlify personal access token, created from your avatar menu under User settings → Applications → Personal access tokens → New access token. The token is shown only once and must have an expiration, so rotate this secret before it expires.
  • NETLIFY_SITE_ID: the Project ID from the Netlify project's Project configuration → General → Project details → Project information. Netlify renamed sites to projects, but this is the same value the CLI and API call the site ID.
• netlify.toml tells Netlify to skip its own git-triggered production builds (its ignore command exits 0 when Netlify's CONTEXT is production), so pushes to main no longer publish anything while deploy previews for pull requests keep working. After the first tag deploy, confirm in the Netlify deploy log that a push to main shows as skipped rather than published. If the repository is ever unlinked from Netlify entirely, pull request previews stop but the tag workflow still deploys.

Previewing a specific version locally

make sync-docs VERSION=v2.1.0
make serve

make sync-docs without VERSION syncs from main and the site shows no version label.

Finding files to edit

The Trickster documentation site uses Hugo with the Docsy theme, which is installed from npm as @docsy/theme (see package.json). For more detailed information on the site infrastructure, see the Hugo and Docsy documentation.

Site-specific templates live in layouts/ and override Docsy's files of the same path. UI string overrides live in i18n/en.yaml.

Editing styles

To override styles, edit the SCSS files in the assets/scss directory. Use these two files as follows:

• _styles_project.scss: edit this file to override Docsy styles or change the current styles.
• _variables_project.scss: declare SCSS variables in this file that you can use elsewhere, and override Docsy and Bootstrap 5 variables.

Updating Docsy

Update the pinned version in package.json (for example with npm install --save-dev @docsy/theme@X.Y.Z), then review the Docsy changelog for changes to the files overridden in layouts/.

Using the documentation site locally

Prerequisites

• Hugo, extended edition, at the version set by HUGO_VERSION in netlify.toml (Docsy requires 0.160.1 or later)
• Node.js 24 or later, with npm

The npm dependencies include the Dart Sass compiler that Hugo uses to build the site's styles. The make targets put it on Hugo's PATH, so run Hugo through them (or through npm run hugo -- ARGS).

Running the website locally

1. At the command line, within the Trickster documentation root directory, run the following command:

   make serve
   

   This installs the npm dependencies (npm ci) when needed, then starts hugo server.

2. Open your web browser and type http://localhost:1313 in your navigation bar. Changes you make to the site will immediately show up in your browser after you save.

License

© Trickster Authors 2021 | Documentation Distributed under CC-BY-4.0

© 2021 The Linux Foundation. All rights reserved. The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our Trademark Usage page.