ContextQMD
Back to Opa

Contributing Documentation

docs/docs/contrib-docs.md

1.18.06.0 KB
Original Source

Contributing to the documentation is one of the best ways to get started contributing to the OPA project. The OPA documentation is often the first place people go for help and so any improvements can be very impactful. Thank you in advance for contributing to the documentation!

Local Development

Those contributing to the OPA website and documentation must first install the Node packages to run it. The following commands are run relative to the docs/ directory.

bash
cd docs
make install

Once these have been installed, a live updating development server can be started by running:

bash
make dev

:::tip Note the Docusaurus server will not restart when you change the docusaurus.config.js.

If you are working on the website code (not only the documentation content) you might find the following command useful to reload the site when changing the configuration files too using entr:

bash
find . -name docusaurus.config.js -o -name sidebars.js | entr -c -r make dev

:::

You can run a local build of the website using the build. This will also show a summary of any broken links or anchors.

bash
make build

This will build a version of the site as it is deployed to the Netlify CDN.

docs Directory Structure

  • docs/ contains the main documentation content.
  • src/ is where custom pages and components are defined. In addition, some dynamically processed content such as that for the /ecosystem/* pages is managed here.
    • pages contains the designs and assets used for custom pages not under /docs/.
    • lib contains shared Javascript functions and sidebar configuration.
    • theme contains customizations to the Docusaurus theme components.
    • data/cli.json is automatically updated from the make task generate-cli-docs.
  • functions/ is used loaded by Netlify to run a number of edge functions for interactive purposes or complex redirects.

Documentation File Format

Documentation is written primarily as Markdown. However, the use of React components is available too. A number of components are used to provide more advanced features such as:

  • Interactive Rego examples
  • Two column layouts
  • Linking to relevant pages in the /ecosystem section
  • Mermaid diagrams containing asset references

Generally, this is not required, but feel free to ask in PRs or in Slack if you have questions. src/theme/MDXComponents.js contains a list of components that are available for use in any Markdown file. Additional components can be imported if needed on a one off basis.

Creating a Local Branch

To get started, fork the OPA repository and create a local branch for your Docs changes. Check out the Development Guide if you need some help setting this up.

Updating Existing Documentation

Navigate to the docs folder in your local environment. Each top level item in the documentation nav will have an associated markdown file in the documentation folder. Locate the file you wish to update and confirm the title in the YAML frontmatter matches. Once you've located the correct page, edit the markdown page as necessary.

Adding New Pages

In the case where you want to add a topic that doesn't fit nicely into any of the existing pages, it may make sense to add a new page. Create a markdown file in the content folder and add the appropriate YAML frontmatter heading. Aside from the title, you may wish to set sidebar_position.

You may also wish to update src/lib/sidebars.js to place your new page in the correct location.

Formatting your changes

Make sure to format your changes correctly by running dprint fmt in the docs folder. This will fix any formatting issues.

Testing your changes

Once you have made your updates, the next step is to test that they look as expected. To test your changes, you can run make dev. Note, broken links will only be checked when Docusaurus builds the site, so you will need to run make build to check for broken links if needed. This will be done when generating the preview site anyway.

Submitting a Pull Request

Once you've tested your changes and you're happy with how they look, commit them to your branch and open a pull request. If this is your first time opening a pull request with the OPA repository, check out the Contributing Code Guide. Once your PR has been received a Netlify preview will be automatically created, check the PR for a unique link.

:::warning Please review OPA's AI Guidelines if you're using any generative AI tooling. :::

Having trouble?

Reach out in the #contributors channel on the OPA Slack to ask for help.

OPA Ecosystem Additions

The OPA Ecosystem is a showcase of projects that are built with or integrated with OPA. If you have a project that you would like to showcase, please open a PR with two files:

Both files should have the same 'id', e.g. if your project is called foobar, then the markdown file should be named foobar.md and the icon file is named foobar.{png|svg}.

You will need to restart the Docusaurus dev server to see the changes if previewing locally.

Sub-project Documentation

Documentation for the OPA sub-projects each have their own home. Check out their documentation sites to see how to contribute.

  • Gatekeeper docs for Kubernetes Admission Control
  • Conftest docs for validating your structured configuration data, like YAML and HCL files