3.4 KiB
Development on documentation
tl;dr
You will need to use following make targets
before creating a pull request!
make install
make check
Features
- Linting of markdown documents
- Spell checking
- Link checking
Specifications
This repository checks against following specification:
Languages
Supported languages are:
Prerequisites
To run all the linters please install for your OS:
Installation
For linting and all the checks you need several npm packages. The following command installs all necessary npm dependencies:
make install
This installs all dependencies into a local node_modules
folder. Make
adds
this to your execution path automatically. If you install the modules somewhere
else please make sure this folder is in your execution path. On macOS or Linux
you probably need to export your Path like this:
export PATH=my/path/to/node_modules/.bin:$PATH
Checks
To enforce good spelling and specification conformity there are several checks
as Makefile
targets defined. To run all checks please execute:
make check
As an alternative to make it is possible to utilize npm-run-all for testing:
npm run-script test
Individual checks
If you want to run individual checks see the targets and the description below. There are always Makefile targets. If you prefer npm for testing you can run every individual check like so:
npm runscript my-individual-check
See the package-json file for help.
Markdown linter
Markdown linting. See the rules here.
make markdownlint
Overrides
Sometimes it is not possible to be commonmark conform. In this rare cases an inline tag to skip linting is possible.
Candidates are tables.
<!-- markdownlint-disable-->
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
<!-- markdownlint-enable-->
Additionally html image tags can be allowed globally. This is useful if you need to resize images, since commonmark has no annotation for this.
This is done with a .markdownlint.json override file which would look something like this:
{
"no-inline-html": {
"allowed_elements": [
"img",
"table"
]
}
}
For more information how to tweak overrides consult the markdown linter documentation mentioned above.
Spell checker
English
Spell checking in American English (en_US).
make spellcheck-en
German
Not implemented yet.
Overrides
Add any additional words to the .spelling file and use the make target to sort and clean them before adding these to master.
make format-spelling
Please note sometimes overriding is not the way to go. For example there may be three ways for the word TeleTan (TeleTAN, teleTAN) in this repository. The documents should stick to one variation.
Link resolver
All cross references and external URLs are resolved.
make checklinks
Inconsiderate language scanner
This checks against profanity and inconsiderate language. This is help full for non-natives to detect words that could be inconsiderate. This utilizes alex
make detect-inconsiderate-language