|
| 1 | +# `units` docs |
| 2 | + |
| 3 | +This buildchain is a self-contained build system for the `units` documentation. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +The buildchain uses [VitePress](https://vitepress.dev/) via a Docker container to facilitate writing the docs as [markdown](https://vitepress.dev/guide/markdown), linting them via [textlint](https://textlint.github.io/), building them as HTML files with bundled assets, and publishing them automatically via a [GitHub action](https://docs.github.com/en/actions). |
| 8 | + |
| 9 | +It also uses a [Rollup](https://rollupjs.org/) [sitemap plugin](https://github.com/aminnairi/rollup-plugin-sitemap) to generate a `sitemap.xml` for the generated docs. |
| 10 | + |
| 11 | +The markdown sources for the docs and assets are in the `docs/docs/` directory. |
| 12 | + |
| 13 | +The built distribution docs are created via the `build-and-deploy-docs.yaml` |
| 14 | + |
| 15 | +## Prerequisites |
| 16 | + |
| 17 | +To run the buildchain for development purposes: |
| 18 | + |
| 19 | +- You must have [Docker Desktop](https://www.docker.com/products/docker-desktop/) (or the equivalent) installed |
| 20 | + |
| 21 | +## Commands |
| 22 | + |
| 23 | +This buildchain uses `make` as an interface to the buildchain. The following commands are available from the `buildchain/` directory: |
| 24 | + |
| 25 | +- `make image-build` - Build the Docker image & run `npm install`. This command must be run once before using the Docker container. |
| 26 | +- `make dev` - Start Vite HMR dev server while writing/editing the docs. Click on the link displayed in the terminal to open the docs up |
| 27 | +- `make lint` - Run `textlint` on the docs, reporting on any errors and warnings |
| 28 | +- `make fix` - Run `textlint` on the docs, automatically fixing any errors, and reporting any warnings |
| 29 | +- `make clean` - Remove `node_modules/` and `package-lock.json` to start clean (need to run `make image-build` after doing this, see below) |
| 30 | +- `make npm XXX` - Run an `npm` command inside the container, e.g.: `make npm run lint` or `make npm install` |
| 31 | +- `make ssh` - Open up a shell session into the buildchain Docker container |
| 32 | +- `make build` - Do a local distribution build of the docs; normally not needed since they are built & deployed via GitHub action |
| 33 | + |
| 34 | +## Docs versioning |
| 35 | + |
| 36 | +Each major version of the plugin corresponds to a major version of Craft. |
| 37 | + |
| 38 | +Each major version of the plugin has separate documentation that needs to be updated when changes span plugin versions. |
| 39 | + |
| 40 | +The latest version of the docs that correspond to the latest version of the plugin is always the root of the docs tree, with older versions appearing in sub-directories: |
| 41 | + |
| 42 | +``` |
| 43 | +│ index.html |
| 44 | +├── v4 |
| 45 | +│ └── index.html |
| 46 | +├── v3 |
| 47 | +│ └── index.html |
| 48 | +``` |
| 49 | + |
| 50 | +The docs are entirely separate, but linked to eachother via a version menu, configured in the `docs/docs/.vitepress/config.ts` file. |
| 51 | + |
| 52 | +## Algolia Docsearch |
| 53 | + |
| 54 | +The docs uses [Algolia Docsearch](https://docsearch.algolia.com/) to index them, and allow for easy searching via a search field with auto-complete. |
| 55 | + |
| 56 | +Algolia Docsearch is configured in the `docs/docs/.vitepress/config.ts` file. |
| 57 | + |
| 58 | +## textlint |
| 59 | + |
| 60 | +The buildchain uses [textlint](https://textlint.github.io/) to automatically fix errors on build, and also issue writing style warnings. |
| 61 | + |
| 62 | +`textlint` automatically uses any rules added to the `docs/package.json` file, which can be overridden or customized via the `docs/.textlintrc.js` file. |
| 63 | + |
| 64 | +See the [textlint docs](https://textlint.github.io/docs/getting-started.html) for details. |
| 65 | + |
| 66 | +## Overriding environment variables |
| 67 | + |
| 68 | +The `Makefile` contains sane defaults for most things, but you can override them via environment variables if you need to. |
| 69 | + |
| 70 | +For instance, if you want to change the `DOCS_DEST` environment variable to change where `make build` builds the docs locally, you can set it before running any buildchain `make` commands: |
| 71 | +```bash |
| 72 | +env DOCS_DEST=../path/to/some/dir make build |
| 73 | +``` |
| 74 | +...or use any other method for [setting environment variables](https://www.twilio.com/blog/how-to-set-environment-variables.html). This environment variable needs to be set in the shell where you run the buildchain's various `make` commands from, so setting it in your project's `.env` file won't work. |
0 commit comments