golioth / docs

Creative Commons Attribution Share Alike 4.0 International
6 stars 11 forks source link

Golioth Docs

The Golioth documentation website is built using Docusaurus 2.

Contributor Information

Please use the .editorconfig file when editing/adding documentation. This will instruct your code editor to follow some simple formatting guidelines such as:

VS Code

Formatting can be enabled automatically in VS Code by enabling the following Plugins:

Gitpod

A pre-configured VS Code instance is available by clicking the Gitpod badge to open a contributor workspace instance:

Open in Gitpod

Automatic hard wrapping in this Gitpod instance can be turned on by pressing CTRL comma to open settings, then search for rewrap auto wrap.

Neovim (Vim)

EditorConfig is supported natively in Neovim. Support can be added to Vim using the editorconfig-vim plugin.

Hard breaks will be added to lines automatically and you can manually reflow paragraphs using qgap and sentences using gqas.

Installation

npm install

Local Development

npm start

This command starts a local development server and open up a browser window. Most changes are reflected live without having to restart the server.

Build

npm run build:dev (or :prod)

This command generates static content into the build directory and can be served using any static contents hosting service.

Device Catalog

The device catalog is automatically generated. To update it, run this command from the project root directory:

npm run build-device-catalog

Quickstart guides can be added in the docs/hardware/6-catalog/quickstart directory and enabled by adding a node in the scripts/device-catalog/support.json file.

Documentation on automatic generation and adding customized pages for supported boards can be found in the device catalog README.

Deployment to Firebase Hosting

Deploy to Golioth Docs Dev site

npm run fb-deploy-dev

Deploy to Golioth Docs Prod Site

npm run fb-deploy-prod

Maintainers of the Golioth docs merging into the main branch will also automatically deploy to production (based on the CI system setup)

Versioning

In Ubuntu, the default npm install will not be up to date with the required npm packages. Consider using nvm to choose an LTS solution that will work better with Docusaurus V2.