--- title: Contributing Documentation --- 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](https://github.com/open-policy-agent/opa/tree/main/docs). ```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](https://github.com/eradman/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](./contrib-development/#fork-clone-create-a-branch) if you need some help setting this up. ## Updating Existing Documentation Navigate to the [docs](https://github.com/open-policy-agent/opa/tree/main/docs/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](./contrib-code). 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](./contrib-code#ai-guidelines) if you're using any generative AI tooling. ::: ## Having trouble? Reach out in the [#contributors](https://openpolicyagent.slack.com/archives/C02L1TLPN59) channel on the [OPA Slack](https://slack.openpolicyagent.org/) to ask for help. ## OPA Ecosystem Additions The [OPA Ecosystem](/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: - A markdown file in [docs/src/data/ecosystem/entries](https://github.com/open-policy-agent/opa/tree/main/docs/src/data/ecosystem/entries) - An icon file in [docs/static/img/ecosystem-entry-logos](https://github.com/open-policy-agent/opa/tree/main/docs/static/img/ecosystem-entry-logos) 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](https://open-policy-agent.github.io/gatekeeper/website/docs/) docs for Kubernetes Admission Control - [Conftest](https://www.conftest.dev/) docs for validating your structured configuration data, like YAML and HCL files