paketo-website
Website for Paketo Buildpacks
Every day at 0500, a cron job runs to check for broken links on the deployed Paketo site.
Development
Prerequisites
Navigating this repo
- HTML lives in
layouts/
, including partials (HTML snippets) that are reused across multiple pages. - SCSS and Javascript live in
assets/
- Much of the CSS uses the BEM naming methodology.
- Hugo automatically compiles our SCSS into CSS. This is a feature of Hugo extended version.
Serving Locally
To Serve docs at http://localhost:1313:
npm install && hugo server
Testing links
To ensure that documentation cross-referencing is done correctly (i.e. no links are broken), we use built in Hugo shortcodes {{< ref >}}
and {{< relref >}}
in our documentation. (See Hugo docs). As a heuristic check for non-shortcoded internal links in the docs markdown, run
scripts/check-internal-links.sh
We also check whether external links on the site (e.g. a link to buildpacks.io) are valid, using a link checker called muffet. It's written in Golang!
To quickly check most links on the rendered site, run
scripts/check-links.sh --quick
This uses the power of goroutines to check our external links at lightning speed -- but avoids Github links to escape rate limiting.
To run a more complete link check (including Github links), run
scripts/check-links.sh
Checking spelling
The site uses the
spellchecker-cli to check
spelling in documentation markdown. To quickly spellcheck the entire /content
directory, run
scripts/check-spelling.sh
Custom dictionary
This repo contains a dictionary of custom regular expressions to add to the default spellcheck dictionary. It is in scripts/.util/spellcheck-dictionary.txt. Items are case sensitive. See spellchecker's documentation for more details.
Excluding part of a document
If part of the docs is failing the spellcheck, it can be wrapped in an exclude block. Adding to the custom dictionary is usually preferred.
Contributing
- Open a PR against the main branch if you'd like to make a change to the site.
- If you're already a Contributor, when you open a PR, a GHA will automatically deploy an ephemeral version of the staging site based on your PR branch. A bot will comment on your PR with the staging URL.
- Otherwise, a Maintainer can manually trigger a deploy of your PR. A bot will comment with the staging URL.
- Join website-related conversations in the #website channel of the Paketo slack instance.
Deployment
This repo uses a GHA workflow to automatically deploy commits on main
to the
Paketo site using GitHub Pages.