Running workflow
Once you have cloned your new docs repository, you will want to be able to know how to start previews, lint, build, and do all the necessary things in development.
Ideally, you would be somewhat acquainted with npm or yarn project workflows, as Docusaurus is a React-based project.
👨💻 Committing to your repo
As part of running npm run prepare when initializing this repo, husky is installed to manage pre-commit hooks.
All commits are linted with commitlint with the conventional rules found in package.json.
lint-staged is used to run checks on certain staged Git files when committing. The commands that are run and on what files can be found in the package.json under the lint-staged key.
It is recommended to use the command git commit only after staging files.
You should generally avoid git commit -m or similar commands which pass in the command-line or args like --allow-empty.
See example of git commit flow
📦 npm commands and scripts
Here is an exhaustive list of what each npm script does in the package.json.
This is likely to change every so often and documentation may not be updated to reflect it always.
Please open an issue or PR to address it!
🐎 npm run start
Run Docusaurus locally on port http://localhost:3000 to preview and supports automatic refresh when changes are made. This is usually used in development while making changes to Markdown or certain configuration files.
Not all changes made are supported by the automatic refresh and may require restarting the command.
👷 npm run build
Build Docusaurus for production into the ./build directory of the root folder of this project.
It is usually not necessary to do this in development and is usually only used by CI when building to be deployed.
There is still an open issue regarding proper and stable CSS insertion ordering that may differ between npm run start and npm run build results.
Please see here for more details.
This is usually not an issue and can be mitigated with adding !important to CSS styles.
📑 npm run build:docs
If you have chosen to use docusaurus-plugin-openapi-docs plugin for integrating OpenAPI to your docs, then this command will clean existing generated Markdown API docs and re-generate them.
This command is bundled into the npm run build command.
You can safely remove this script from the package.json if you are not using the plugin.
🖋️ npm run swizzle
Swizzling allows more advanced customization of React Components in Docusaurus beyond simple CSS modifications.
✈️ npm run deploy
Built-in as part of Docusaurus for deploying project.
This command should not be necessary to use at all.
⌦ npm run clear
If you are running into some issues with error when running npm run start, it is recommended to use the clear command to remove all generated assets, caches or build artifacts.
📺 npm run serve
This is to be run after the npm run build command as it will serve the files generated by the build output from the ./build directory for local viewing.
As npm run build is for production building or debugging production build issues, it should not be necessary to use npm runs serve except where those two scenarios require it.
🌎 npm run write-translations
Only needed where translations are to be added.
🌎 npm run write-heading-ids
Only needed where translations are to be added.
⌨️ npm run typecheck
Typechecking with TypeScript and tsconfig.json.
⌨️ npm run typecheck-staged
Typechecking staged-only files which is used by lint-staged when committing.
🧼 npm run lint
Combined command which includes spell check, JS/TS linting, and CSS linting.
🧼 npm run lint:js
Lint JS/TS with ESLint.
🧼 npm run lint:spelling
Checking spelling with CSpell.
📚 Adding new words to the dictionary
It's possible that you will use a word in your content that is not known to the linter, and your build, or commit, will fail.
If this happens, take a look at project-words.txt in the root directory of your project; if the word that the linter caught is correctly spelled, and you wish it to pass the linter's test, add it to project-words.txt, save, add and commit those changes, and see if it passes.
🧼 npm run lint:style
Lint CSS files with specific styling.
🧼 npm run lint:fix
Pass the --fix CLI argument to npm run lint:js to attempt to fix issues.
🖨️ npm run format
Run Prettier to format code before commit for consistency in the repo.
🥗 npm run prepare
After npm install for the very first time, husky is installed for Git pre-commit hooks.