diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 488e4de473..25a8976587 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -105,6 +105,60 @@ To build Nx on Windows, you need to use WSL. - Run `yarn install` in WSL. Yarn will compile several dependencies. If you don't run `install` in WSL, they will be compiled for Windows. - Run `yarn test` and other commands in WSL. +## Documentation Contributions + +We would love for you to contribute to our documentation as well! Please feel welcome to submit fixes or enhancements to our existing documentation pages and the `nx-dev` application in this repo. + +### Documentation Structure + +#### Documentation Pages + +Our documentation pages can be found within this repo under the `docs` directory. Pages that we consider framework specific are nested in their own subdirectories - otherwise they should be nested within the `docs/shared` directory. + +The `docs/map.json` file is considered our source of truth for our site's structure, and should be updated when adding a new page to our documentation to ensure that it is included in the documentation site. We also run automated scripts based on this `map.json` data to safeguard against common human errors that could break our site. + +#### Nx-Dev Application + +Our public `nx.dev` documentation site is a [Next.js](https://nextjs.org/) application, that can be found in the `nx-dev` directory of this repo. + +The `nx-dev/nx-dev/public/documentation` directory contains `.md` files that are generated from the `docs` directory when new releases are cut. As such, these should not be changed when submitting a change to existing docs. + +Jump to [Running the Documentation Site Locally](#running-the-documentation-site-locally) to see how to preview your changes while serving. + +### Changing Generated API documentation + +`.md` files documenting the API for our CLI (including executor and generator API docs) are generated via the corresponding `schema.json` file for the given command. + +After adjusting the `schema.json` file, `.md` files for these commands can be generated by running: + +```bash +yarn documentation +``` + +This will update the corresponding contents of the `docs` directory. These are generated automatically on push (via husky) as well. + +Note that adjusting the `schema.json` files will also affect the CLI manuals and Nx Console behavior, in addition to adjusting the docs. + +### Running the Documentation Site Locally + +To run `nx-dev` locally, run the command: + +```bash +npx nx serve nx-dev +``` + +You can then access the application locally at `localhost:4200`. + +By default, the site displays the `Latest` cut release of the docs. To see your current changes in the docs be sure to select `Preview` from the version selection box of the site. + +Selecting Preview from Version Selection box + +### PR Preview + +When submitting a PR, this repo will automatically generate a preview of the `nx-dev` application based on the contents of your pull request. + +Once the preview site is launched, a comment will automatically be added to your PR with the link your your PR's preview. To check your docs changes, make sure to select `Preview` from the version selection box of the site. + ## Submission Guidelines ### Submitting an Issue diff --git a/images/selecting-preview-from-version-selection-box.png b/images/selecting-preview-from-version-selection-box.png new file mode 100644 index 0000000000..fe74e7c2aa Binary files /dev/null and b/images/selecting-preview-from-version-selection-box.png differ