Setup

nodecg-io has a steadily growing and improving documentation. We are using Markdown to describe the content and mkdocs for the deployment to the webpage (https://nodecg.io). If you want to get to know the standard Markdown syntax, take a look at this guide. We also use many plugins, so you may take a look at a curated list of examples of the extended syntax.

Clone this repo

If you installed the development version nodecg-io with the CLI, you may have already cloned the nodecg-io-docs repository into the docs folder inside nodecg-io directory. Then you will have to fork the official repo and add your fork as a remote:

git remote add <name> (https://github.com/<your-user-name>/nodecg-io-docs.git)

Else clone your fork into a desired directory with:

git clone https://github.com/<your-user-name>/nodecg-io-docs.git

Repository structure

|-- .github ................ CI workflows
|-- .vscode ................ VS Code specific configs
|-- docs ................... All files included in the documentation
|   |-- assets ................ other files used (images)
|   |-- contribute ............ Section on development and documentation
|   |-- getting_started ....... Section on first use
|   |-- samples ............... documentation for the sample bundles
|   |-- dependencies.md ....... One huge UML diagram (auto generated)
|   |-- index.md .............. Home screen of the documentation
|   `-- services.md ........... Availabel Services (auto generated)
|-- .markdownlint.json ..... markdownlint config file
|-- .prettierrc.json ....... prettier (formatter) config file
`-- mkdocs.yml ............. mkdocs config file

Install dependencies to use the preview

You will need a Python 3 installed. You will also need to install mkdocs with pip:

pip install -r requirements.txt

Now you can serve the local version with:

mkdocs serve

Now you can access it in your browser under http://127.0.0.1:8000/.

Using VS Code

Extensions

For the folks out there who are using VS Code to edit these documents you can use the recommended extensions of this workspace by using the @recommended filter in the extensions panel. Those extensions will format (Prettier) and lint (markdownlint) the markdown files, and live check many typos and grammar (LTeX). Also, the built-in preview will parse more of our used syntax.

Tasks

Note

You will need prettier and markdownlint installed in your path.

You may also benefit from the preconfigured serve task. It can be accessed with Ctrl + Shift + B (CMD + Shift + B on macOS). This will format and lint the files and then serve them to you.