chore: Integrate Markdownlint

2022-10-10 01:37:09 -04:00 · 2022-10-10 01:37:09 -04:00 · 4d1c6b213d
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@ -22,8 +22,11 @@ jobs:
      - name: Install Dependencies
        run: npm ci

-      - name: Run Linting
-        run: npm run offline-lint:js
+      - name: Run Markdownlint
+        run: npm run lint:md
+
+      - name: Run ESLint
+        run: npm run lint:js

      - name: Run tests
        run: npm test
--- a/.markdownlint-cli2.jsonc
+++ b/.markdownlint-cli2.jsonc
@ -0,0 +1,11 @@
+{
+  "config": {
+    "default": true,
+    "MD013": false,
+    "MD024": {
+      "allow_different_nesting": true
+    },
+    "MD026": false
+  },
+  "ignores": ["**/node_modules/**"]
+}
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@ -1,8 +1,3 @@
 {
-  "typescript.tsdk": "node_modules/typescript/lib",
-  "editor.tabSize": 2,
-  "typescript.format.semicolons": "insert",
-  "editor.formatOnSave": true,
-  "javascript.preferences.quoteStyle": "single",
-  "typescript.preferences.quoteStyle": "single"
+  "typescript.tsdk": "node_modules/typescript/lib"
 }
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@ -1,3 +1,5 @@
+# Contributing to this project
+
 <!-- This file is currently generic with the exception of mentioning how
     to report security-related bugs to Microsoft. -->

@ -8,8 +10,6 @@ FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
 contact [opencode@microsoft.com](mailto:opencode@microsoft.com)
 with any additional questions or comments.

-# Contributing to this project
-
 As an open source project contributions are more than welcome and are
 essential to keeping the project interesting and useful. Everyone is
 welcome, and there are many ways to contribute to the project beyond
@ -52,10 +52,10 @@ collaboration.
 1. Fork the repo on GitHub, cloning on your machine
 2. Create a branch with your changes.

- Please keep the branch specific to your contribution
- Please use logical commits with helpful, concise commit messages
- Follow the coding style of the project
- Run follow any build or test scripts. Contribute new tests.
+   - Please keep the branch specific to your contribution
+   - Please use logical commits with helpful, concise commit messages
+   - Follow the coding style of the project
+   - Run follow any build or test scripts. Contribute new tests.

 3. Create a [Pull Request](https://help.github.com/articles/using-pull-requests/) with your contribution.

--- a/README.md
+++ b/README.md
@ -211,7 +211,7 @@ The `main` module of the defined default-assets-package should resolve to the
 path to serve content from. Since the default version uses \[ancient\] Grunt to build the
 assets, it returns the `__dirname` + `/public`, which is the output/built location for Grunt.

-```
+```bash
 npm install
 cd default-assets-package
 npm install
@ -219,11 +219,11 @@ npm install

 ### Build

-```
+```bash
 npm run build
 ```

-You need to rebuild the default-assets-package if you change something. [see Static Site Assets](#static-site-assets)
+You need to rebuild the default-assets-package if you change something. [see Static Site Assets](docs/staticSiteAssets.md)

 ### Codespaces instructions

@ -284,7 +284,7 @@ the open source upstream and should be excluded currently.

 ### Building the Docker image

-```
+```bash
 docker build -t opensource-management-portal .
 ```

@ -346,7 +346,7 @@ you can configure the following extreme minimum working set to use the app.
 The central operations token is a personal access token that is a **org owner**
 of the GitHub org(s) being managed.

-```
+```env
 DEBUG_ALLOW_HTTP=1
 GITHUB_CENTRAL_OPERATIONS_TOKEN=a github token for the app
 GITHUB_ORGANIZATIONS_FILE=../../env-orgs.json
--- a/SECURITY.md
+++ b/SECURITY.md
@ -1,6 +1,6 @@
 <!-- BEGIN MICROSOFT SECURITY.MD V0.0.5 BLOCK -->

-## Security
+# Security

 Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/Microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet), [Xamarin](https://github.com/xamarin), and [our GitHub organizations](https://opensource.microsoft.com/).

--- a/docs/api.md
+++ b/docs/api.md
@ -1,5 +1,3 @@
-[Docs index](index.md)
-
 # API

 There is an initial API implementation available to help partner teams
@ -65,7 +63,7 @@ You can technically provide the token for the username and/or password.
 An API key may be authorized for a specific API endpoint or scope. Please verify when you
 are granted API access that you have access to the endpoint that you intend to.

-# User link management
+## User link management

 Information about the list of linked users who have a corporate relationship with other accounts is available.

@ -79,22 +77,22 @@ data instead of calling this API exhaustively while performing work.

 - The parameter `showOrganizations` (default implicitly to true) can be set to `false` or `0` to _not_ show users' GitHub organization memberships. This reduces the size of the link payload.

-## Get all linked users
+### Get all linked users

 > GET /api/people/links

-### Response
+#### Response

 HTTP

-```
+```http
 Status: 200 OK
 Content-Type: application/json; charset=utf-8
 ```

 Body

-```
+```json
 [
  {
    "github": {
@ -102,7 +100,7 @@ Body
      "login": "username",
      "organizations": [
        "OrganizationName1",
-        "OrganizationName2
+        "OrganizationName2"
      ],
      "avatar": "url"
    },
@ -123,7 +121,7 @@ Body
      ],
      "avatar": "url"
    },
-    "isServiceAccount" true,
+    "isServiceAccount": true,
    "serviceAccountContact": "contact@domain.com",
    "aad": {
      "preferredName": "serviceaccount2@domain.com",
@ -135,44 +133,42 @@ Body
 ]
 ```

-## Get a specific linked user
+### Get a specific linked user

 This API will retrieve information about a specific user. The first API version to support this was `2017-03-08`.

-### by Link ID
+#### by Link ID

 > GET /api/people/links:linkid

-### by GitHub username
+#### by GitHub username

 > GET /api/people/links/github/:login

 Where `login` is a GitHub username, case insensitive.

-#### Response
+##### Response

 If a link is not found for the GitHub user

-```
+```http
 Status: 404 Not Found
 ```

 If a link is found

-```
+```http
 Status: 200 OK
 ```

 Response body:

-```
+```json
 {
  "github": {
    "id": 2,
    "login": "username2",
-    "organizations": [
-      "OrganizationName2"
-    ]
+    "organizations": ["OrganizationName2"]
  },
  "aad": {
    "alias": "alias2",
@ -184,39 +180,37 @@ Response body:
 }
 ```

-### by Azure Active Directory ID
+#### by Azure Active Directory ID

-> This API returns an array if there is at least one matching account or accounts. To support scenarios with other account types or even multiple accounts such as service accounts, it is up to your application to determine how to handle more than one account. Order is not guaranteed.
+This API returns an array if there is at least one matching account or accounts. To support scenarios with other account types or even multiple accounts such as service accounts, it is up to your application to determine how to handle more than one account. Order is not guaranteed.

 > GET /api/people/links/aad/:id

 Where `id` is an AAD ID.

-#### Response
+##### Response

 If a link is not registered for this user

-```
+```http
 Status: 404 Not Found
 ```

 If a link is found

-```
+```http
 Status: 200 OK
 ```

 Response body:

-```
+```json
 [
  {
    "github": {
      "id": 2,
      "login": "username2",
-      "organizations": [
-        "OrganizationName2"
-      ]
+      "organizations": ["OrganizationName2"]
    },
    "aad": {
      "alias": "alias2",
@ -233,15 +227,15 @@ It is most common that the array will be of length === 1.

 If there are no results, instead of an HTTP 200, you will receive 404 (no empty array).

-## Create a link
+### Create a link

 Required API scope: `link`

 > POST /api/people/links

-### Request
+#### Request

-```
+```text
 BODY
 {
  "corporate": {
@ -255,23 +249,23 @@ BODY

 > If the account is a Service Account, the `corporate` object should also include a field called `serviceAccountMail` that points to a contact for the service account.

-### Response
+#### Response

-```
+```http
 Status: 201 OK
 ```

 'Location' header includes a pointer to the resource by link ID.

-# Repository management
+## Repository management

-## Create a repo
+### Create a repo

 > This API requires that your API key be authorized for the `createRepo` scope

 This example uses a pure POST request plus headers for authorization:

-```
+```text
 POST https://endpoint/api/orgName/repos?api-version=2016-12-01

 HEADERS
@ -410,7 +404,7 @@ OUTPUT BODY

 This example uses headers on top of a standard GitHub client:

-```
+```text
 POST https://endpoint/api/Microsoft/repos

 HEADERS
@ -433,7 +427,7 @@ BODY

 ```

-Bare minimum GitHub body component, with the type JSON, is the `name` field. You can see the GitHub API documentation here: https://developer.github.com/v3/repos/#create
+Bare minimum GitHub body component, with the type JSON, is the `name` field. You can see the GitHub API documentation here: <https://developer.github.com/v3/repos/#create>

 - name (name of the repo)
 - private (true/false)
@ -454,7 +448,7 @@ Team permissions must be set at create time as well. The API will support up to

 Team permission (ms.teams) value:

-```
+```json
 {
  "pull": [1],
  "push": [],
@ -464,9 +458,7 @@ Team permission (ms.teams) value:

 Always try and provide a minimum number of administrator teams, same goes for write teams (push), and encourage the standard Git workflow.

-# API
-
-Internal Microsoft-specific notes
+## Internal Microsoft-specific notes

 Microsoft-required fields and components:

--- a/docs/changelog.md
+++ b/docs/changelog.md
@ -1,5 +1,3 @@
-[Docs index](index.md)
-
 # Changes

 ## 2021
--- a/docs/configuration.md
+++ b/docs/configuration.md
@ -1,6 +1,4 @@
-[Docs index](index.md)
-
-## Configuration
+# Configuration

 The configuration story for this application has been evolving over time. At this time, the
 following configuration elements are available at this time, each with a distinct purpose.
@ -18,7 +16,7 @@ A GitHub organization(s) configuration file in JSON format is required as of ver
 With the current configuration story, a `CONFIGURATION_ENVIRONMENT` variable is required, as well
 as a secret for AAD to get KeyVault bootstrapped. That requirement will go away soon.

-### Configuring organizations
+## Configuring organizations

 When installed as a GitHub App, the installations can be added into the "dynamic settings" system where
 the org info is stored in an entity database. This allows the app and jobs to pick up the latest configuration
@ -27,11 +25,11 @@ without needing redeployment.
 Alternatively, a static JSON file can be provided to store configuration details and other information
 about your GitHub orgs that the app will manage.

-#### Static orgs
+### Static orgs

 The opensource-portal only shows GitHub-organizations which are configured in a specific file. The path for this file is handed over with the environment-variable `GITHUB_ORGANIZATIONS_FILE`, which specifies the relative path of this file from the `data`-folder as root directory. This JSON-file has to be created, here is an example of the organizations-file:

-```
+```json
 [
  {
    "name": "ContosoDev",
@ -76,7 +74,7 @@ Here is a short overview about the meanings of the different parameters:
 - templates: GitHub repository templates
 - locked: joining this organization via the opensource-portal is disabled

-### PostgreSQL Configuration
+## PostgreSQL Configuration

 To run the opensource-portal with a postgres database, you need to [setup postgres](https://www.postgresql.org/docs/11/runtime.html) and initialize the database by running the `pg.sql`-file in the psql-terminal.
 It's recommended to [run postgres in a docker container](https://hub.docker.com/_/postgres), there is also an official docker image called `postgres` for building.
@ -87,7 +85,7 @@ Additionally set the name of the linking-table (`tableName` parameter), if the t
 There is also a script in the `scripts` folder that can blast the `pg.sql` insertions into a new database. Be
 sure to configure grants and your user accounts with the concept of least privilege required.

-### Cache Configuration
+## Cache Configuration

 For caching GitHub-requests with Redis, [setup a redis database](https://redis.io/topics/quickstart) ([running Redis in a docker container](https://hub.docker.com/_/redis/) is recommended, there is an official docker image called `redis` for building).

@ -95,7 +93,7 @@ After Redis setup is complete, set your Redis configs in the `config/redis.json`

 Other providers available include Azure Blob (slower but cheap), Cosmos DB, and a hybrid Cosmos+Blob.

-### KeyVault Secret Support
+## KeyVault Secret Support

 Any configuration string property can be resolved to a KeyVault secret.

@ -111,7 +109,7 @@ URI: a value of `keyvault://username@samplevault.vault.azure.net/secrets/secret-
 get the secret and its metadata, setting the configuration value to the `username` tag, if
 present.

-#### Key rotation
+### Key rotation

 As configuration, including secrets, is resolved at startup, any key rotation would need
 to include a restart of the app service.
--- a/docs/data.md
+++ b/docs/data.md
@ -1,16 +1,14 @@
-[Docs index](index.md)
+# Data, databases, etc...

-# Data, databases, etc.
+## Data quality issues

-### Data quality issues
-
-_username casing_
+### username casing

 The original table store for usernames (GitHub users, etc.) was case sensitive
 for stored data. However, the newer Postgres system uses case insensitive
 indexes. As a result there may be latent bugs.

-_date/times_
+### date/times

 - Approval 'decisionTime' field was buggy in the past
 - Approval 'requested' field was buggy in the past
@ -18,7 +16,7 @@ _date/times_
 Going forward these fields are ISO8601 date time fields. Existing data may
 continue to have poor formats, and may be an issue during data migration.

-### Migration of data
+## Migration of data

 The `localEnvironment` TypeScript file is intended to permit prototyping and
 local development hacks.
--- a/docs/decisions/2013-02-portal.md
+++ b/docs/decisions/2013-02-portal.md
@ -1,3 +1,5 @@
+# Decision: Portal
+
 The original management solution for the Azure GitHub organization was similar to what a GitHub
 employee might call "entitlements": an actual GitHub repository with the source of truth in files,
 and the GitHub pull request and other tools used to manage updating that source of truth, plus
--- a/docs/decisions/2013-03-eventual-consistency.md
+++ b/docs/decisions/2013-03-eventual-consistency.md
@ -1,3 +1,5 @@
+# Decision: Eventual Consistency
+
 A majority of the user interface within the management portal is _eventually consistent_ and not
 necessarily an accurate real-time view.

--- a/docs/decisions/2016-08-js.md
+++ b/docs/decisions/2016-08-js.md
@ -1,3 +1,5 @@
+# Decision: JavaScript
+
 This portal is implemented in JavaScript / Node.

 The original Microsoft Open Source Programs Office shipped a .NET (C#) internal product,
--- a/docs/decisions/2017-06-postgres.md
+++ b/docs/decisions/2017-06-postgres.md
@ -1,3 +1,5 @@
+# Decision: Postgres
+
 A decision was made in June 2017 to move away from the data stores used
 by the Azure open source portal and to evolve to something more appropriate
 for the scale and size of the app.
--- a/docs/decisions/2019-08-client-apis.md
+++ b/docs/decisions/2019-08-client-apis.md
@ -1,3 +1,5 @@
+# Decision: Client APIs
+
 Starting in 2019, logic from the portal began moving out of Express-based routes (never a good
 design to start with), and into helper functions and APIs.

--- a/docs/features.md
+++ b/docs/features.md
@ -1,5 +1,3 @@
-[Docs index](index.md)
-
 # Feature flags

 Under development, configuration values in `config/features.json` map
--- a/docs/githubApp.md
+++ b/docs/githubApp.md
@ -1,8 +1,6 @@
-[Docs index](index.md)
-
 # How the app authenticates with GitHub

-**Modern GitHub App is strongly recommended**
+**Modern GitHub App is strongly recommended!**

 The service as a monolith is able to partition keys and authentication for
 GitHub resources at the organization level.
--- a/docs/jobs.md
+++ b/docs/jobs.md
@ -1,5 +1,3 @@
-[Docs index](index.md)
-
 # Jobs

 There are automated cronjobs available to help keep things running smoothly,
--- a/docs/metrics.md
+++ b/docs/metrics.md
@ -1,5 +1,3 @@
-[Docs index](index.md)
-
 # Metrics

 ## Application Insights
--- a/docs/scripts.md
+++ b/docs/scripts.md
@ -1,5 +1,3 @@
-[Docs index](index.md)
-
 # Scripts

 > this file is incomplete
--- a/docs/staticSiteAssets.md
+++ b/docs/staticSiteAssets.md
@ -1,5 +1,3 @@
-[Docs index](index.md)
-
 # Static Site Assets

 To simplify the app build process, and also make it easier for us to open
--- a/features/sudo/sudo.md
+++ b/features/sudo/sudo.md
@ -33,12 +33,12 @@ Overrides are available to allow the company-specific system to provide the
 org sudo instance for an organization, if you wish to implement a different
 approach, or use a different company-internal system for these decisions.

-## Debug flags
+### Debug flags

 There is an environmental off-switch enabled that can turn off sudo, allowing for testing
 as a regular user in local environments. That env variable name is `DEBUG_GITHUB_ORG_SUDO_OFF`.

-# portal sudo
+## portal sudo

 Portal sudo applies sudo for all organizations configured within the application.
 Used by system administrators typically.
@ -46,7 +46,7 @@ Used by system administrators typically.
 The original design was to use the sudo configuration from the first/primary GitHub org
 that was configured in the environment.

-## Feature flag: FEATURE_FLAG_ALLOW_PORTAL_SUDO
+### Feature flag: FEATURE_FLAG_ALLOW_PORTAL_SUDO

 > This feature is not on by default.

@ -63,7 +63,7 @@ Can be:
 For the security group provider, configuration should set `SUDO_PORTAL_SECURITY_GROUP_ID` to the
 security group ID to use.

-## Debug flags
+### Debug flags

 Two environment variables designed for development work exist:

--- a/package-lock.json
+++ b/package-lock.json
@ -120,6 +120,7 @@
        "jest": "29.1.2",
        "jest-junit": "14.0.1",
        "lint-staged": "^13.0.3",
+        "markdownlint-cli2": "^0.5.1",
        "prettier": "2.7.1",
        "ts-jest": "29.0.3",
        "ts-node": "10.9.1",
@ -7496,6 +7497,15 @@
      "integrity": "sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==",
      "dev": true
    },
+    "node_modules/linkify-it": {
+      "version": "4.0.1",
+      "resolved": "https://registry.npmjs.org/linkify-it/-/linkify-it-4.0.1.tgz",
+      "integrity": "sha512-C7bfi1UZmoj8+PQx22XyeXCuBlokoyWQL5pWSP+EI6nzRylyThouddufc2c1NDIcP9k5agmN9fLpA7VNJfIiqw==",
+      "dev": true,
+      "dependencies": {
+        "uc.micro": "^1.0.1"
+      }
+    },
    "node_modules/lint-staged": {
      "version": "13.0.3",
      "resolved": "https://registry.npmjs.org/lint-staged/-/lint-staged-13.0.3.tgz",
@ -7999,6 +8009,135 @@
        "tmpl": "1.0.5"
      }
    },
+    "node_modules/markdown-it": {
+      "version": "13.0.1",
+      "resolved": "https://registry.npmjs.org/markdown-it/-/markdown-it-13.0.1.tgz",
+      "integrity": "sha512-lTlxriVoy2criHP0JKRhO2VDG9c2ypWCsT237eDiLqi09rmbKoUetyGHq2uOIRoRS//kfoJckS0eUzzkDR+k2Q==",
+      "dev": true,
+      "dependencies": {
+        "argparse": "^2.0.1",
+        "entities": "~3.0.1",
+        "linkify-it": "^4.0.1",
+        "mdurl": "^1.0.1",
+        "uc.micro": "^1.0.5"
+      },
+      "bin": {
+        "markdown-it": "bin/markdown-it.js"
+      }
+    },
+    "node_modules/markdown-it/node_modules/entities": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/entities/-/entities-3.0.1.tgz",
+      "integrity": "sha512-WiyBqoomrwMdFG1e0kqvASYfnlb0lp8M5o5Fw2OFq1hNZxxcNk8Ik0Xm7LxzBhuidnZB/UtBqVCgUz3kBOP51Q==",
+      "dev": true,
+      "engines": {
+        "node": ">=0.12"
+      },
+      "funding": {
+        "url": "https://github.com/fb55/entities?sponsor=1"
+      }
+    },
+    "node_modules/markdownlint": {
+      "version": "0.26.2",
+      "resolved": "https://registry.npmjs.org/markdownlint/-/markdownlint-0.26.2.tgz",
+      "integrity": "sha512-2Am42YX2Ex5SQhRq35HxYWDfz1NLEOZWWN25nqd2h3AHRKsGRE+Qg1gt1++exW792eXTrR4jCNHfShfWk9Nz8w==",
+      "dev": true,
+      "dependencies": {
+        "markdown-it": "13.0.1"
+      },
+      "engines": {
+        "node": ">=14"
+      }
+    },
+    "node_modules/markdownlint-cli2": {
+      "version": "0.5.1",
+      "resolved": "https://registry.npmjs.org/markdownlint-cli2/-/markdownlint-cli2-0.5.1.tgz",
+      "integrity": "sha512-f3Nb1GF/c8YSrV/FntsCWzpa5mLFJRlO+wzEgv+lkNQjU6MZflUwc2FbyEDPTo6oVhP2VyUOkK0GkFgfuktl1w==",
+      "dev": true,
+      "dependencies": {
+        "globby": "13.1.2",
+        "markdownlint": "0.26.2",
+        "markdownlint-cli2-formatter-default": "0.0.3",
+        "micromatch": "4.0.5",
+        "strip-json-comments": "5.0.0",
+        "yaml": "2.1.1"
+      },
+      "bin": {
+        "markdownlint-cli2": "markdownlint-cli2.js",
+        "markdownlint-cli2-config": "markdownlint-cli2-config.js",
+        "markdownlint-cli2-fix": "markdownlint-cli2-fix.js"
+      },
+      "engines": {
+        "node": ">=14"
+      }
+    },
+    "node_modules/markdownlint-cli2-formatter-default": {
+      "version": "0.0.3",
+      "resolved": "https://registry.npmjs.org/markdownlint-cli2-formatter-default/-/markdownlint-cli2-formatter-default-0.0.3.tgz",
+      "integrity": "sha512-QEAJitT5eqX1SNboOD+SO/LNBpu4P4je8JlR02ug2cLQAqmIhh8IJnSK7AcaHBHhNADqdGydnPpQOpsNcEEqCw==",
+      "dev": true,
+      "peerDependencies": {
+        "markdownlint-cli2": ">=0.0.4"
+      }
+    },
+    "node_modules/markdownlint-cli2/node_modules/globby": {
+      "version": "13.1.2",
+      "resolved": "https://registry.npmjs.org/globby/-/globby-13.1.2.tgz",
+      "integrity": "sha512-LKSDZXToac40u8Q1PQtZihbNdTYSNMuWe+K5l+oa6KgDzSvVrHXlJy40hUP522RjAIoNLJYBJi7ow+rbFpIhHQ==",
+      "dev": true,
+      "dependencies": {
+        "dir-glob": "^3.0.1",
+        "fast-glob": "^3.2.11",
+        "ignore": "^5.2.0",
+        "merge2": "^1.4.1",
+        "slash": "^4.0.0"
+      },
+      "engines": {
+        "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/markdownlint-cli2/node_modules/slash": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/slash/-/slash-4.0.0.tgz",
+      "integrity": "sha512-3dOsAHXXUkQTpOYcoAxLIorMTp4gIQr5IW3iVb7A7lFIp0VHhnynm9izx6TssdrIcVIESAlVjtnO2K8bg+Coew==",
+      "dev": true,
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/markdownlint-cli2/node_modules/strip-json-comments": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-5.0.0.tgz",
+      "integrity": "sha512-V1LGY4UUo0jgwC+ELQ2BNWfPa17TIuwBLg+j1AA/9RPzKINl1lhxVEu2r+ZTTO8aetIsUzE5Qj6LMSBkoGYKKw==",
+      "dev": true,
+      "engines": {
+        "node": ">=14.16"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/markdownlint-cli2/node_modules/yaml": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.1.1.tgz",
+      "integrity": "sha512-o96x3OPo8GjWeSLF+wOAbrPfhFOGY0W00GNaxCDv+9hkcDJEnev1yh8S7pgHF0ik6zc8sQLuL8hjHjJULZp8bw==",
+      "dev": true,
+      "engines": {
+        "node": ">= 14"
+      }
+    },
+    "node_modules/mdurl": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/mdurl/-/mdurl-1.0.1.tgz",
+      "integrity": "sha512-/sKlQJCBYVY9Ers9hqzKou4H6V5UWc/M59TH2dvkt+84itfnq7uFOMLpOiOS4ujvHP4etln18fmIxA5R5fll0g==",
+      "dev": true
+    },
    "node_modules/media-typer": {
      "version": "0.3.0",
      "resolved": "https://registry.npmjs.org/media-typer/-/media-typer-0.3.0.tgz",
@ -10686,6 +10825,12 @@
        "node": ">=4.2.0"
      }
    },
+    "node_modules/uc.micro": {
+      "version": "1.0.6",
+      "resolved": "https://registry.npmjs.org/uc.micro/-/uc.micro-1.0.6.tgz",
+      "integrity": "sha512-8Y75pvTYkLJW2hWQHXxoqRgV7qb9B+9vFEtidML+7koHUFapnVJAZ6cKs+Qjz5Aw3aZWHMC6u0wJE3At+nSGwA==",
+      "dev": true
+    },
    "node_modules/uid-safe": {
      "version": "2.1.5",
      "resolved": "https://registry.npmjs.org/uid-safe/-/uid-safe-2.1.5.tgz",
@ -16900,6 +17045,15 @@
      "integrity": "sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==",
      "dev": true
    },
+    "linkify-it": {
+      "version": "4.0.1",
+      "resolved": "https://registry.npmjs.org/linkify-it/-/linkify-it-4.0.1.tgz",
+      "integrity": "sha512-C7bfi1UZmoj8+PQx22XyeXCuBlokoyWQL5pWSP+EI6nzRylyThouddufc2c1NDIcP9k5agmN9fLpA7VNJfIiqw==",
+      "dev": true,
+      "requires": {
+        "uc.micro": "^1.0.1"
+      }
+    },
    "lint-staged": {
      "version": "13.0.3",
      "resolved": "https://registry.npmjs.org/lint-staged/-/lint-staged-13.0.3.tgz",
@ -17284,6 +17438,96 @@
        "tmpl": "1.0.5"
      }
    },
+    "markdown-it": {
+      "version": "13.0.1",
+      "resolved": "https://registry.npmjs.org/markdown-it/-/markdown-it-13.0.1.tgz",
+      "integrity": "sha512-lTlxriVoy2criHP0JKRhO2VDG9c2ypWCsT237eDiLqi09rmbKoUetyGHq2uOIRoRS//kfoJckS0eUzzkDR+k2Q==",
+      "dev": true,
+      "requires": {
+        "argparse": "^2.0.1",
+        "entities": "~3.0.1",
+        "linkify-it": "^4.0.1",
+        "mdurl": "^1.0.1",
+        "uc.micro": "^1.0.5"
+      },
+      "dependencies": {
+        "entities": {
+          "version": "3.0.1",
+          "resolved": "https://registry.npmjs.org/entities/-/entities-3.0.1.tgz",
+          "integrity": "sha512-WiyBqoomrwMdFG1e0kqvASYfnlb0lp8M5o5Fw2OFq1hNZxxcNk8Ik0Xm7LxzBhuidnZB/UtBqVCgUz3kBOP51Q==",
+          "dev": true
+        }
+      }
+    },
+    "markdownlint": {
+      "version": "0.26.2",
+      "resolved": "https://registry.npmjs.org/markdownlint/-/markdownlint-0.26.2.tgz",
+      "integrity": "sha512-2Am42YX2Ex5SQhRq35HxYWDfz1NLEOZWWN25nqd2h3AHRKsGRE+Qg1gt1++exW792eXTrR4jCNHfShfWk9Nz8w==",
+      "dev": true,
+      "requires": {
+        "markdown-it": "13.0.1"
+      }
+    },
+    "markdownlint-cli2": {
+      "version": "0.5.1",
+      "resolved": "https://registry.npmjs.org/markdownlint-cli2/-/markdownlint-cli2-0.5.1.tgz",
+      "integrity": "sha512-f3Nb1GF/c8YSrV/FntsCWzpa5mLFJRlO+wzEgv+lkNQjU6MZflUwc2FbyEDPTo6oVhP2VyUOkK0GkFgfuktl1w==",
+      "dev": true,
+      "requires": {
+        "globby": "13.1.2",
+        "markdownlint": "0.26.2",
+        "markdownlint-cli2-formatter-default": "0.0.3",
+        "micromatch": "4.0.5",
+        "strip-json-comments": "5.0.0",
+        "yaml": "2.1.1"
+      },
+      "dependencies": {
+        "globby": {
+          "version": "13.1.2",
+          "resolved": "https://registry.npmjs.org/globby/-/globby-13.1.2.tgz",
+          "integrity": "sha512-LKSDZXToac40u8Q1PQtZihbNdTYSNMuWe+K5l+oa6KgDzSvVrHXlJy40hUP522RjAIoNLJYBJi7ow+rbFpIhHQ==",
+          "dev": true,
+          "requires": {
+            "dir-glob": "^3.0.1",
+            "fast-glob": "^3.2.11",
+            "ignore": "^5.2.0",
+            "merge2": "^1.4.1",
+            "slash": "^4.0.0"
+          }
+        },
+        "slash": {
+          "version": "4.0.0",
+          "resolved": "https://registry.npmjs.org/slash/-/slash-4.0.0.tgz",
+          "integrity": "sha512-3dOsAHXXUkQTpOYcoAxLIorMTp4gIQr5IW3iVb7A7lFIp0VHhnynm9izx6TssdrIcVIESAlVjtnO2K8bg+Coew==",
+          "dev": true
+        },
+        "strip-json-comments": {
+          "version": "5.0.0",
+          "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-5.0.0.tgz",
+          "integrity": "sha512-V1LGY4UUo0jgwC+ELQ2BNWfPa17TIuwBLg+j1AA/9RPzKINl1lhxVEu2r+ZTTO8aetIsUzE5Qj6LMSBkoGYKKw==",
+          "dev": true
+        },
+        "yaml": {
+          "version": "2.1.1",
+          "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.1.1.tgz",
+          "integrity": "sha512-o96x3OPo8GjWeSLF+wOAbrPfhFOGY0W00GNaxCDv+9hkcDJEnev1yh8S7pgHF0ik6zc8sQLuL8hjHjJULZp8bw==",
+          "dev": true
+        }
+      }
+    },
+    "markdownlint-cli2-formatter-default": {
+      "version": "0.0.3",
+      "resolved": "https://registry.npmjs.org/markdownlint-cli2-formatter-default/-/markdownlint-cli2-formatter-default-0.0.3.tgz",
+      "integrity": "sha512-QEAJitT5eqX1SNboOD+SO/LNBpu4P4je8JlR02ug2cLQAqmIhh8IJnSK7AcaHBHhNADqdGydnPpQOpsNcEEqCw==",
+      "dev": true,
+      "requires": {}
+    },
+    "mdurl": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/mdurl/-/mdurl-1.0.1.tgz",
+      "integrity": "sha512-/sKlQJCBYVY9Ers9hqzKou4H6V5UWc/M59TH2dvkt+84itfnq7uFOMLpOiOS4ujvHP4etln18fmIxA5R5fll0g==",
+      "dev": true
+    },
    "media-typer": {
      "version": "0.3.0",
      "resolved": "https://registry.npmjs.org/media-typer/-/media-typer-0.3.0.tgz",
@ -19312,6 +19556,12 @@
      "resolved": "https://registry.npmjs.org/typescript/-/typescript-4.8.4.tgz",
      "integrity": "sha512-QCh+85mCy+h0IGff8r5XWzOVSbBO+KfeYrMQh7NJ58QujwcE22u+NUSmUxqF+un70P9GXKxa2HCNiTTMJknyjQ=="
    },
+    "uc.micro": {
+      "version": "1.0.6",
+      "resolved": "https://registry.npmjs.org/uc.micro/-/uc.micro-1.0.6.tgz",
+      "integrity": "sha512-8Y75pvTYkLJW2hWQHXxoqRgV7qb9B+9vFEtidML+7koHUFapnVJAZ6cKs+Qjz5Aw3aZWHMC6u0wJE3At+nSGwA==",
+      "dev": true
+    },
    "uid-safe": {
      "version": "2.1.5",
      "resolved": "https://registry.npmjs.org/uid-safe/-/uid-safe-2.1.5.tgz",
--- a/package.json
+++ b/package.json
@ -19,19 +19,24 @@
    "organization"
  ],
  "scripts": {
-    "offline-lint:js": "eslint .",
-    "fix": "eslint --fix .",
-    "start": "node ./dist/bin/www",
-    "start-in-container": "node ./bin/www",
+    "build": "tsc",
+    "fix:js": "eslint --fix .",
+    "fix:md": "markdownlint-cli2-fix \"**/*.md\"",
+    "fix": "npm run fix:js && npm run fix:md",
+    "lint:js": "eslint .",
+    "lint:md": "markdownlint-cli2 \"**/*.md\"",
+    "lint": "npm run lint:js && npm run lint:md",
+    "prepare": "husky install",
    "start-4000": "PORT=4000 DEBUG=startup node ./dist/bin/www",
-    "test": "jest",
+    "start-in-container": "node ./bin/www",
+    "start": "node ./dist/bin/www",
    "test:ci": "jest --watchAll=false --reporters=default --reporters=jest-junit",
-    "build": "./node_modules/typescript/bin/tsc",
-    "prepare": "husky install"
+    "test": "jest"
  },
  "lint-staged": {
    "*": "prettier --write --ignore-unknown",
-    "*.{js,ts}": "eslint --fix"
+    "*.{js,ts}": "eslint --fix",
+    "*.md": "markdownlint-cli2-fix"
  },
  "jest-junit": {
    "suiteNameTemplate": "{filepath}",
@ -165,6 +170,7 @@
    "jest": "29.1.2",
    "jest-junit": "14.0.1",
    "lint-staged": "^13.0.3",
+    "markdownlint-cli2": "^0.5.1",
    "prettier": "2.7.1",
    "ts-jest": "29.0.3",
    "ts-node": "10.9.1",