cwa-documentation/INSTALL.md

# Development on documentation

## tl;dr

**You will need to use following `npm scripts` before creating a pull request!**

1. `npm install`
2. `npm test`

## Features

* Linting of markdown documents
* Spell checking
* Link checking

## Specifications

This repository checks against following specification:

* [Markdown Commonmark](https://spec.commonmark.org/)

### Languages

Supported languages are:

* [English US](https://en.wikipedia.org/wiki/ISO/IEC_8859-1)

## Prerequisites

To run all the linters please install for your OS:

* [npm](https://github.com/nodesource/distributions)

## Installation

For linting and all the checks you need several npm packages. The following
command installs all necessary npm dependencies:

```shell
npm install
```

This installs all dependencies into a local `node_modules` folder.

## Checks

To enforce good spelling and specification conformity there are several checks
defined as `npm run-script` targets. To run all checks please execute:

```shell
npm test
```

### Individual checks

If you want to run individual checks see the targets and the description below.
Every individual check can be run like so:

```shell
npm runscript my-individual-check
```
See the package-json file for help.

#### Markdown linter

Markdown linting. See the rules [here](https://github.com/DavidAnson/markdownlint).

```shell
npm run-script 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.

```html
<!-- 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:

```json
{
    "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).

```shell
npm run-script spellcheck
```

##### German

Not implemented yet.

##### Overrides

Add any additional words to the .spelling file and use the target to sort
and clean them before adding these to master.

```shell
npm run-script 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.

```shell
npm run-script 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](https://github.com/get-alex/alex)

```shell
npm run-script detect-inconsiderate-language
```