codeoverflow-org · hlxid · Nov 1, 2021 · Oct 31, 2021 · Nov 1, 2021 · Nov 1, 2021
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,6 @@
 build/
 .idea
-.vscode
+.vscode/*
+!.vscode/extensions.json
+!.vscode/tasks.json
+!.vscode/settings.json
diff --git a/.ignore-files.txt → .prettierignore b/.ignore-files.txt → .prettierignore
@@ -1,2 +1,2 @@
 docs/dependencies.md
-docs/services.md
+docs/services.md
diff --git a/.vscode/extensions.json b/.vscode/extensions.json
@@ -0,0 +1,10 @@
+{
+    "recommendations": [
+        "davidanson.vscode-markdownlint",
+        "esbenp.prettier-vscode",
+        "jebbs.plantuml",
+        "valentjn.vscode-ltex",
+        "yzhang.markdown-all-in-one",
+        "jebbs.markdown-extended"
+    ]
+}
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -0,0 +1,27 @@
+{
+    "editor.formatOnSave": true,
+    "editor.defaultFormatter": "esbenp.prettier-vscode",
+    "markdownExtended.disabledPlugins": "table-of-contents,footnote,abbr,deflist,sup,sub,checkbox,attrs,kbd,underline,multimd-table,container,mark",
+    "ltex.language": "en-GB",
+    "ltex.checkFrequency": "edit",
+    // This could cause more false positives
+    "ltex.additionalRules.enablePickyRules": true,
+    "ltex.hiddenFalsePositives": {
+        "en-GB": [
+            //  nodecg-io will always be written lowercease
+            "{'rule': 'UPPERCASE_SENTENCE_START', 'sentence': '^nodecg-io'}",
+            // Admonition markers are not recognised by the Markdown parser of LTeX
+            "{'rule': 'PUNCTUATION_PARAGRAPH_END', 'sentence': '^ATTENTION'}",
+            "{'rule': 'PUNCTUATION_PARAGRAPH_END', 'sentence': '^CAUTION'}",
+            "{'rule': 'PUNCTUATION_PARAGRAPH_END', 'sentence': '^DANGER'}",
+            "{'rule': 'PUNCTUATION_PARAGRAPH_END', 'sentence': '^ERROR'}",
+            "{'rule': 'PUNCTUATION_PARAGRAPH_END', 'sentence': '^EXAMPLE'}",
+            "{'rule': 'PUNCTUATION_PARAGRAPH_END', 'sentence': '^HINT'}",
+            "{'rule': 'PUNCTUATION_PARAGRAPH_END', 'sentence': '^IMPORTANT'}",
+            "{'rule': 'PUNCTUATION_PARAGRAPH_END', 'sentence': '^NOTE'}",
+            "{'rule': 'PUNCTUATION_PARAGRAPH_END', 'sentence': '^TIP'}",
+            "{'rule': 'PUNCTUATION_PARAGRAPH_END', 'sentence': '^WARNING'}",
+            "{'rule': 'PUNCTUATION_PARAGRAPH_END', 'sentence': '^ADMONITION'}"
+        ]
+    }
+}
diff --git a/.vscode/tasks.json b/.vscode/tasks.json
@@ -0,0 +1,51 @@
+{
+    // See https://code.visualstudio.com/docs/editor/tasks
+    // for the documentation about the tasks.json format
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "mkdocs serve locally",
+            "detail": "mkdocs serve",
+            "type": "shell",
+            "command": "mkdocs serve",
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            },
+            "presentation": {
+                "reveal": "always",
+                "panel": "new"
+            },
+            "dependsOn": [
+                "npm: format",
+                "npm: lint"
+            ]
+        },
+        {
+            "type": "npm",
+            "script": "format",
+            "problemMatcher": [],
+            "label": "npm: format",
+            "detail":"prettier -w **.md",
+            "group": "test",
+            "presentation": {
+                "reveal": "never",
+                "panel": "shared",
+                "revealProblems": "onProblem"
+            },
+        },
+        {
+            "type": "npm",
+            "script": "lint",
+            "problemMatcher": [],
+            "label": "npm: lint",
+            "detail": "markdownlint -p .prettierignore .",
+            "group": "test",
+            "presentation": {
+                "reveal": "never",
+                "panel": "shared",
+                "revealProblems": "onProblem"
+            }
+        }
+    ]
+}
diff --git a/docs/contribute/contribute.md b/docs/contribute/contribute.md
@@ -1,16 +1,23 @@
 # How to contribute
 
-There are many ways to contribute to nodecg-io: logging bugs, submitting pull requests, reporting issues, and creating suggestions.
-
-First you'll need an installation of nodecg-io. Please refer to the [installation guide](../getting_started/install.md) and create a development installation.
-The CLI asks you whether you want to clone the documentation. It's highly recommended that you do that and update the documentation as you add new services or features.
-To be able to create Pull Requests you should fork the corresponding repositories and add them as a remote (update URL for e.g., documentation repository):
+There are many ways to contribute to nodecg-io: logging bugs, submitting pull
+requests, reporting issues, and creating suggestions. You can also contribute to
+this [documentation](docs_setup.md).
+
+First you'll need an installation of nodecg-io. Please refer to the
+[installation guide](../getting_started/install.md) and create a development
+installation. The CLI asks you whether you want to clone the documentation. It's
+highly recommended that you do that and update the documentation as you add new
+services or features. To be able to create Pull Requests you should fork the
+corresponding repositories and add them as a remote (update URL for e.g.,
+documentation repository):
 
 ```shell
 git remote add fork https://github.com/[YOUR_USERNAME]/nodecg-io.git
 ```
 
-Then you can create a new branch, do your changes, create commits and publish the branch to your fork using the following command:
+Then you can create a new branch, do your changes, create commits and publish
+the branch to your fork using the following command:
 
 ```shell
 git push fork my-branch
@@ -20,30 +27,36 @@ git push fork my-branch
 
 ### VS Code
 
-In Visual Studio Code you can start the build task with
-<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>B</kbd> (<kbd>CMD</kbd>+<kbd>Shift</kbd>+<kbd>B</kbd> on macOS).
-The incremental builder will do an initial full build.  
-The watch builder will watch for file changes and compile those changes incrementally, giving you a fast, iterative coding experience.
-It will even stay running in the background if you close VS Code.
-You can resume it by starting the build task with
-<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>B</kbd> (<kbd>CMD</kbd>+<kbd>Shift</kbd>+<kbd>B</kbd>) again.  
-You can kill the build task by pressing <kbd>Ctrl</kbd>+<kbd>D</kbd> in the task terminal (<kbd>CMD</kbd>+<kbd>D</kbd>) on macOS.  
-Errors and warnings will be shown in the status bar at the bottom left of the editor. You can view the error list using `View | Errors and Warnings` or pressing <kbd>Ctrl</kbd>+<kbd>P</kbd> and then <kbd>!</kbd> (<kbd>CMD</kbd>+<kbd>P</kbd> and <kbd>!</kbd> on macOS)
+In Visual Studio Code you can start the build task with <kbd>Ctrl</kbd> +
+<kbd>Shift</kbd> + <kbd>B</kbd> (<kbd>CMD</kbd> + <kbd>Shift</kbd> +
+<kbd>B</kbd> on macOS). The incremental builder will do an initial full build.  
+The watch builder will watch for file changes and compile those changes
+incrementally, giving you a fast, iterative coding experience. It will even stay
+running in the background if you close VS Code. You can resume it by starting
+the build task with <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>B</kbd>
+(<kbd>CMD</kbd> + <kbd>Shift</kbd> + <kbd>B</kbd>) again.  
+You can kill the build task by pressing <kbd>Ctrl</kbd> + <kbd>D</kbd> in the
+task terminal (<kbd>CMD</kbd> + <kbd>D</kbd>) on macOS.  
+Errors and warnings will be shown in the status bar at the bottom left of the
+editor. You can view the error list using `View | Errors and Warnings` or
+pressing <kbd>Ctrl</kbd> + <kbd>P</kbd> and then <kbd>!</kbd> (or
+<kbd>CMD</kbd> + <kbd>P</kbd> and <kbd>!</kbd> on macOS).
 
 ### Terminal
 
 You can also use you terminal to build nodecg-io:
 
-```
+```shell
 cd path/to/nodecg-io
 npm run build
 ```
 
-To do a full rebuild instead of just an incremental build you can use `npm run rebuild`.
+To do a full rebuild instead of just an incremental build you can use
+`npm run rebuild`.
 
 The watch builder can be activated here too:
 
-```
+```shell
 cd path/to/nodecg-io
 npm run watch
 ```
@@ -54,36 +67,58 @@ To test the changes you simply need to start/restart NodeCG.
 
 ## Adding dependencies to packages
 
-This project uses [npm workspaces](https://docs.npmjs.com/cli/v7/using-npm/workspaces/) to manage our monorepo, and most importantly link all our packages together.
-Because of linking you should not use `npm install xyz --save` to add dependencies because npm can't get the development version of internal packages like `nodecg-io-core`. Doing so will result in an error and break the link.
-Instead, you should edit the `package.json` directly using a text editor and the run `npm install` in the repository root.
+This project uses
+[npm workspaces](https://docs.npmjs.com/cli/v7/using-npm/workspaces/) to manage
+our monorepo, and most importantly link all our packages together. Because of
+linking you should not use `npm install xyz --save` to add dependencies because
+npm can't get the development version of internal packages like
+`nodecg-io-core`. Doing so will result in an error and break the link. Instead,
+you should edit the `package.json` directly using a text editor and the run
+`npm install` in the repository root.
 
 ## Open a Pull Request
 
-Once you have implemented your feature or fixed a bug push it to your fork and start a Pull Request.
+Once you have implemented your feature or fixed a bug push it to your fork and
+start a Pull Request.
 
 ## Merge Upstream Changes
 
-Occasionally you will want to merge changes in the upstream repository (the official code repo) with your fork.
+Occasionally you will want to merge changes in the upstream repository (the
+official code repo) with your fork.
 
-```
+```shell
 cd path/to/nodecg-io
 git checkout master
 git pull https://github.com/codeoverflow-org/nodecg-io master
 ```
 
 Manage any merge conflicts, commit them, and then push them to your fork.
 
-You may also occasionally need to merge upstream master in a pull request. To do that make the above to update your local master, and then merge your local master into your PR branch.
+You may also occasionally need to merge upstream master in a pull request. To do
+that make the above to update your local master, and then merge your local
+master into your PR branch.
 
 ### Where to Contribute
 
-After cloning and building the repo, check out the [issues list](https://github.com/codeoverflow-org/nodecg-io/issues). Issues labelled [`help wanted`](https://github.com/codeoverflow-org/nodecg-io/labels/help%20wanted) are good issues to submit a PR for. Issues labelled [`good first issue`](https://github.com/codeoverflow-org/nodecg-io/labels/good%20first%20issue) are great candidates to pick up if you are in the code for the first time. If you are contributing significant changes, please discuss with the assignee of the issue first before starting to work on the issue.
+After cloning and building the repo, check out the
+[issues list](https://github.com/codeoverflow-org/nodecg-io/issues). Issues
+labelled
+[help wanted](https://github.com/codeoverflow-org/nodecg-io/labels/help%20wanted)
+are good issues to submit a PR for. Issues labelled
+[good first issue](https://github.com/codeoverflow-org/nodecg-io/labels/good%20first%20issue)
+are great candidates to pick up if you are in the code for the first time. If
+you are contributing significant changes, please discuss with the assignee of
+the issue first before starting to work on the issue. You may also contribute to
+this [documentation](docs_setup.md).
 
 ## Suggestions
 
-We're also interested in your feedback. You can submit a suggestion or feature request through the issue tracker. To make this process more effective, we're asking that these include more information to help define them more clearly.
+We're also interested in your feedback. You can submit a suggestion or feature
+request through the issue tracker. To make this process more effective, we're
+asking that these include more information to help define them more clearly.
 
 ## Discussion Etiquette
 
-In order to keep the conversation clear and transparent, please limit discussion to English and keep things on topic with the issue. Be considerate to others and try to be courteous and professional at all times.
+In order to keep the conversation clear and transparent, please limit discussion
+to English and keep things on topic with the issue. Be considerate to others and
+try to be courteous and professional at all times.
diff --git a/docs/contribute/create_sample.md b/docs/contribute/create_sample.md
@@ -1,75 +1,85 @@
 # Create a sample bundle
 
-A sample should have the same name as the service, but it may include a short description in the name after the service name as well.
-E.g. `twitch-chat` or `obs-scenelist`.
+A sample should have the same name as the service, but it may include a short
+description in the name after the service name as well. E.g. `twitch-chat` or
+`obs-scenelist`.
 
-Create a folder in `samples` named after the sample and add a `package.json` and a `tsconfig.json`:
+Create a folder in `samples` named after the sample and add a `package.json` and
+a `tsconfig.json`:
 
-`package.json`
+=== "package.json"
 
-```json
-{
-    "name": "<the sample name>",
-    "private": true,
-    "version": "0.2.0",
-    "nodecg": {
-        "compatibleRange": "^1.1.1",
-        "bundleDependencies": {
-            "nodecg-io-<the service name>": "^0.2.0"
+    ```json
+    {
+        "name": "<the sample name>",
+        "private": true,
+        "version": "0.2.0",
+        "nodecg": {
+            "compatibleRange": "^1.1.1",
+            "bundleDependencies": {
+                "nodecg-io-<the service name>": "^0.2.0"
+            }
+        },
+        "scripts": {
+            "build": "tsc -b",
+            "watch": "tsc -b -w",
+            "clean": "tsc -b --clean"
+        },
+        "license": "MIT",
+        "dependencies": {
+            "nodecg-io-<the service name>": "^0.2.0",
+            "nodecg-io-core": "^0.2.0",
+            "@types/node": "^15.0.2",
+            "nodecg-types": "^1.8.2",
+            "typescript": "^4.2.4"
         }
-    },
-    "scripts": {
-        "build": "tsc -b",
-        "watch": "tsc -b -w",
-        "clean": "tsc -b --clean"
-    },
-    "license": "MIT",
-    "dependencies": {
-        "nodecg-io-<the service name>": "^0.2.0",
-        "nodecg-io-core": "^0.2.0",
-        "@types/node": "^15.0.2",
-        "nodecg-types": "^1.8.2",
-        "typescript": "^4.2.4"
     }
-}
-```
+    ```
 
-`tsconfig.json`
+=== "tsconfig.json"
 
-```json
-{
-    "extends": "../../tsconfig.common.json",
-    "references": [
-        {
-            "path": "../../nodecg-io-core"
-        },
-        {
-            "path": "../../services/nodecg-io-<the service name>"
-        }
-    ]
-}
-```
+    ```json
+    {
+        "extends": "../../tsconfig.common.json",
+        "references": [
+            {
+                "path": "../../nodecg-io-core"
+            },
+            {
+                "path": "../../services/nodecg-io-<the service name>"
+            }
+        ]
+    }
+    ```
+
+Now you can create a file called `extension/index.ts`. Here's a template. Make
+sure you replace all the comments with your own code.
 
-Now you can create a file called `extension/index.ts`. Here's a template. Make sure you replace all the comments with your own code.
+=== "index.ts"
 
-```typescript
-import { NodeCG } from "nodecg-types/types/server";
-import { requireService } from "nodecg-io-core";
-import { TheServicesExportedClient } from "nodecg-io-<the services name>";
+    ```typescript
+    import { NodeCG } from "nodecg-types/types/server";
+    import { requireService } from "nodecg-io-core";
+    import { TheServicesExportedClient } from "nodecg-io-<the services  name>";
 
-module.exports = function (nodecg: NodeCG) {
-    nodecg.log.info("Sample bundle for <the-service-name> started");
+    module.exports = function (nodecg: NodeCG) {
+        nodecg.log.info("Sample bundle for <the-service-name> started");
 
-    const service = requireService<TheServicesExportedClient>(nodecg, "<the-service-name>");
-    service?.onAvailable((client) => {
-        nodecg.log.info("<the-service-name> client has been updated.");
+        const service = requireService<TheServicesExportedClient>(
+            nodecg,
+            "<the-service-name>"
+        );
+        service?.onAvailable((client) => {
+            nodecg.log.info("<the-service-name> client has been updated.");
 
-        // TODO do something with the client to demonstrate the functionality.
-    });
+            // TODO do something with the client to demonstrate the functionality.
+        });
 
-    service?.onUnavailable(() => nodecg.log.info("<the-service-name> client has been unset."));
-};
-```
+        service?.onUnavailable(() =>
+            nodecg.log.info("<the-service-name> client has been unset.")
+        );
+    };
+    ```
 
 ## Next steps