The content and tooling is separated into a few places:
devel/ - Developer documentation for OPA (not part of the website)
website/ - This directory contains all of the Markdown, HTML, Sass/CSS, and other assets needed to build the openpolicyagent.org website. See the section below for steps to build the site and test documentation changes locally. This content is not versioned for each release, it is common scaffolding for the website.
content/ - The raw OPA documentation can be found under the directory. This content is versioned for each release and should have all images and code snippets alongside the markdown content files.
The website (openpolicyagent.org) and doc's hosted there (openpolicyagent.org/docs) have a few components involved with the buildings and hosting.
The static site is generated with Hugo which uses the markdown
in content/ as its content for pages under /docs/*
. There is a script
to generate the previous supported versions, automated via make generate
, and the
latest (current working tree) documentations is under /docs/edge/*
.
The static site content is then hosted by Netlify. To
support backwards compatible URLs (from pre-netlify days) and to have the latest
version of the docs URLs work
openpolicyagent.org/docs/latest the site
relies on Netlify URL redirects and rewrites
which are defined in website/layouts/index.redirects
and are build into a _redirects
file when the Hugo build happens via
make production-build
or make preview-build
.
Because of the different components at play there are a few different ways to test/view the website. The choice depends largely on what is being modified:
Go to Netlify and log-in. Link to your public fork of OPA on github and have it deploy a site. As long as it is public this is free and can be configured to deploy test branches before opening PR's on the official OPA github repo.
This approach gives the best simulation for what the website will behave like once code has merged.
The majorify of this can be done with any markdown renderer (typically built-in or a plug-in for IDE's). The rendered output will be very similar to what Hugo will generate.
This excludes the Hugo shortcodes (places with
{{< SHORT_CODE >}}
in the markdown. To see the output of these you'll need to involve Hugo
The easiest way is to run Hugo locally in dev mode. Changes made will be reflected immediately be the Hugo dev server. See Run the site locally using Docker
This approach will not include the Netlify redirects so urls like
http://localhost:1313/docs/latest/
will not work. You must navigate directly to the version of docs you want to test. Typically this will be http://localhost:1313/docs/edge/.
This requires either using the Full Site Preview or using the local dev tools as described below in: Run the site locally without Docker
The local dev tools will not give live updates as the content changes, but will give the most accurate production simulation.
You can run the site locally with Docker or without Docker.
This MUST be done before you can serve the site locally!
The site will show all versions of doc content from the tagged versions listed in RELEASES.
To generate them run:
make generate
The content then will be placed into docs/website/generated/docs/$VERSION/
.
This will attempt to fetch the latest tags from git. The fetch will be skipped
if the OFFLINE
environment variable is defined. For example:
OFFLINE=1 make generate
Note: running with docker only uses the Hugo server and not Netlify locally. This means that redirects and other Netlify features the site relies on will not work.
make docker-serve
Open your browser to http://localhost:1313 to see the site running locally. The docs are available at http://localhost:1313/docs.
To build and serve the site locally without using Docker, install the following packages on your system:
- The Hugo static site generator
- The Netlify dev CLI
The site will be running from the Hugo dev server and fronted through netlify running as a local reverse proxy. This more closely simulates the production environment but gives live updates as code changes.
Running the website locally requires installing the Hugo static
site generator. The required version of Hugo is listed in the
netlify.toml
configuration file (see the HUGO_VERSION
variable).
Installation instructions for Hugo can be found in the official documentation.
Please note that you need to install the "extended" version of Hugo (with built-in support) to run the site locally. If you get errors like this, it means that you're using the non-extended version:
error: failed to transform resource: TOCSS: failed to transform "sass/style.sass" (text/x-sass): this feature is not available in your current Hugo version
From this directory:
make serve
Watch the console output for a localhost URL (the port is randomized). The docs are available at http://localhost:$PORT/docs.
The OPA site is automatically published using Netlify. Whenever
changes in this directory are pushed to master
, the site will be re-built and
re-deployed.
To check the site's links, first install the htmlproofer
Ruby gem:
gem install htmlproofer
Then run:
make linkcheck