Awesome
Klaw documentation
- Please be aware of our Code of Conduct â¤ī¸
About
This is the Klaw documentation repository. Welcome đ đ You can find source code and all content for our (Klaw documentation site here.
We're using Docusaurus to build our documentation, an optimized site generator in React.
Installation and usage
Requirements
- node needs to be installed.
-> please check nvmrc or the
engines
definition in package.json for version. - We use pnpm (version 8) as a package manager. Read their official documentation how to install pnpm.
This is the setup you need every time. You can find the different ways how to run the local development process below.
Optional
- We use Vale spell checking. The spell check will run in the GitHub pipeline.
To use Vale locally, please make sure you install it:
- It runs on Mac, Linux and Windows. You can find instructions to download and install it at their Installation guide.
- after installation, run
vale sync
on root level
While we check for errors in the pipeline, we also have "warning" and "suggestion" level rules. We recommend running those checks locally, too.
Local development
First, make sure you hare the required technology set up:
- node (see above)
- pnpm (see above)
- optional: Vale (see above)
The, install all needed dependencies and setup the needed githooks:
pnpm install
To start the local development server, run:
pnpm start
đĻ the website will now run on http://localhost:3000/
Scripts used and their actions
âšī¸ You can see all our scripts in the package.json
.
You can also run pnpm run
in your console to get a list of all available scripts.
Please note that you have to set up your local development to use the scripts.
Here are the important ones you're likely to use:
pnpm start
: starts the app for developmentpnpm build
: will build the documentation site and generate all static files in "build". Afterbuild
you can runpnpm serve
to test your build locallypnpm lint
: runs a format check and if no error is found, lints code and markdown files in the project.- the linting script does not mutate your code. See Linting and code formatting for more info.
pnpm reformat
: runs the code formatter (Prettier) as well as the markdown linter in fix mode. This will mutate your code.pnpm markdown-link-check
: checks if there are any broken links. Note: This requires internet connection, as it does check external links, too!- Run
pnpm markdown-link-check -- -o
to only check for internal links (offline mode). - Run
pnpm markdown-link-check -- -q
to only log errors. - Run
pnpm markdown-link-check -- -q /path/your-file.md
to run checks for only one file.
- Run
pnpm check-sidbar
: checks that the file linked in sidebar do exist and that all markdown files indocs
are listed in sidebar.js. It does not warn for files that start with the prefixDRAFT_
.
For these scripts, you need to have Vale installed (see Requirements):
pnpm spell:error
to show only errors (same as in CI)pnpm spell:warn
to show errors as well as warningspnpm spell:warn
to show errors, warnings and suggestions
âšī¸ We are using a custom hook path for enabling pre-commit hooks. This path is set in the local git configuration when
running pnpm install
.
Linting and code formatting
How we keep our app's codebase looking consistent and nice đ đŧ
- Prettier for code formatting
- ESlint and various plugins for linting
- markdownlint in combination with markdownlint-cli to check and format markdown files specially.
Fine-grained scripts for linting and formatting
We provide pnpm lint
as well as pnpm reformat
to check or mutate your changes. We also offer more specific
scripts you can use:
Scripts with lint
do not mutate your code in any way:
pnpm lint:code
- runs a Prettier and ESlint check. This includes basic checks for markdown, but not in depth.pnpm lint:markdown
- runs markdown-lint with more detailed check on markdown files.
To apply findings from lint
and mutate your files:
pnpm reformat:code
- runs Prettier and ESlint in fix mode.pnpm reformat:markdown
- runs markdownlint in fix mode.
âšī¸ It's convenient to let Prettier and ESlint automatically format your code "on save" by your IDE or editor. For markdownlint you can find plugins for some IDE/editors, too.