fe2516b9ba
## Description * fixes all `markdownlint` issues, includeing autogenerated docs * fixes [error] level Vale problems * ## Type of change <!--- Please check the type of change your PR introduces: ---> - [ ] 🌻 Feature - [x] 🐛 Bugfix - [x] 🗺️ Documentation - [ ] 🤖 Test - [ ] 💻 CI/Deployment - [x] 🐹 Trivial/Minor ## Issue(s) ## Test Plan <!-- How will this be tested prior to merging.--> - [x] 💪 Manual - [ ] ⚡ Unit test - [ ] 💚 E2E
70 lines
1.6 KiB
Markdown
70 lines
1.6 KiB
Markdown
# Corso documentation
|
|
|
|
Corso documentation uses [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
|
|
[Mermaid](https://mermaid-js.github.io/mermaid/) provides support for native diagrams in Markdown.
|
|
|
|
## Requirements
|
|
|
|
Developing documentation for Corso requires the following tools on your machine:
|
|
|
|
- `make`
|
|
- Docker
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
make buildimage
|
|
```
|
|
|
|
## Live documentation development
|
|
|
|
```bash
|
|
make dev
|
|
```
|
|
|
|
This command starts a local development server within the Docker container and will expose docs at [http://localhost:3000](http://localhost:3000).
|
|
|
|
## Generating Corso CLI docs
|
|
|
|
```bash
|
|
make genclidocs
|
|
```
|
|
|
|
Corso's CLI documents are auto generated. This command explicitly triggers generating these docs. This step will happen
|
|
automatically for the other commands where this is relevant.
|
|
|
|
## Building static documentation
|
|
|
|
```bash
|
|
make build
|
|
```
|
|
|
|
This command generates static content into the `build` directory for integration with any static contents hosting service.
|
|
|
|
## Style and linting
|
|
|
|
```bash
|
|
# Lint all docs
|
|
make dockercheck
|
|
# Lint specific files and/or folders
|
|
make dockercheck VALE_TARGET="README.md docs/concepts"
|
|
```
|
|
|
|
This command will lint all Markdown files and check them for style issues using the Docker container
|
|
|
|
```bash
|
|
make check
|
|
```
|
|
|
|
Same as `make dockercheck` but runs locally. Requires `vale` to be installed.
|
|
|
|
## Documentation platform development
|
|
|
|
```bash
|
|
make shell
|
|
```
|
|
|
|
Use this command to interactively (and temporarily!) change the contents or
|
|
configuration of the live documentation container image (for example, when
|
|
experimenting with new plugins).
|