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

• Hugo (extended version)
• npm

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.