diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 7d1de60b..469b91ec 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -63,6 +63,37 @@ You can get some hints of whom to contact by looking at [CODEOWNERS](https://git To minimise the overhead of the contributing to the documentation and speed up "time-to-published-docs" we do not have a formal review process. We will start simple, and add more formality as needed. +### Spell checker + +A spell checker workflow runs on all PRs to help catch simple typos. +If the spell checker finds words that it considers misspelled, it will add a comment like [this](https://github.com/eth-cscs/cscs-docs/pull/193#issuecomment-3056795496) to the PR, listing the words that it finds misspelled. + +The spell checker isn't always right and can be configured to ignore words. +Most frequently technical terms, project names, etc. will not be in the dictionaries. +There are three files used to configure words that get ignored: + +- `.github/actions/spelling/allow.txt`: + This is the main file for whitelisting words. + Each line of the file contains a word that is ignored by the spell checker. + All lowercase words are matched with any capitalization, while words containing at least one uppercase letter are matched with the given capitalization. + Using the capitalized word is useful if you always want to ensure the same spelling, e.g. for names. + +- `.github/actions/spelling/patterns.txt`: + This file is used to ignore words that match a given regular expression. + This file is useful to ignore e.g. URLs or markdown references. + Words that have unusual capitalization may also need to be added to this file to make sure they are ignored. + For example, "FirecREST" is normally recognized as two words: "Firec" and "REST", and adding "FirecREST" to `allow.txt` will not ignore the word. + In this case it can be ignored by adding it to `patterns.txt` + +- `.github/actions/spelling/block-delimiters.txt`: + This file can be used to ignore words between begin- and end markers. + For example, code blocks starting and ending with `` ``` `` are ignored from spell checking as they often contain unusual words not in dictionaries. + If adding words to `allow.txt` or `patterns.txt`, or ignoring blocks with `block-delimiters.list`, is not sufficient, you can as a last resort use the HTML comments `` and `` to ignore spell checking for a larger block of text. + The comments will not be rendered in the final documentation. + +Additionally, the file `.github/actions/spelling/only.txt` contains a list of regular expressions used to match which files to check. +Only markdown files under the `docs` directory are checked. + [](){#ref-contributing-guidelines} ## Guidelines