Welcome to the Viam Documentation

Build the docs locally

To be able to build the docs locally, you need to install the following:

• npm
• Hugo
  • macOS/Linux: brew install hugo
  • Windows: https://gohugo.io/getting-started/installing/

You can build the docs for local development using the following command:

To see the production view (without drafts and with minified CSS), run:

Generate HTML docs

To generate the full HTML version of the docs, run:

You can serve the resulting docs with:

python3 -m http.server 9000 --directory public

Test the docs locally

Python snippets

To ensure all Python snippets are properly formatted before creating a commit, install flake8-markdown:

Then, add the following lines to the .git/hooks/pre-commit file in your local repository:

if [ "git diff --diff-filter=d --name-only HEAD | grep '\.md$' | wc -l" ];
then
list= $(git diff --diff-filter=d --name-only HEAD | grep '\.md$')
for item in $list
do
flake8-markdown $item
done
fi

If you don't already have a .git/hooks/pre-commit file in your docs git repo directory, you can copy the existing pre-commit.sample file in that directory as pre-commit to use the sample template, or create a new pre-commit file in that directory with the above content. If you create a new file, you must also make it executable with: chmod +x /path/to/my/.git/hooks/pre-commit.

Check markdown formatting

To ensure your markdown is properly formatted, run:

make markdowntest docs/**/*`

Check for broken links

To check locally for broken links, install htmltest:

Then, and run make htmltest.

Lint JS and Markdown files with Prettier on save

1. Install the Prettier VS Code Extension.
2. Run npm install in the docs folder where you have the docs checked out.
3. Inside VS code, open the user settings.json file: Press CMD+SHIFT+P, type 'settings', select Open User Settings (JSON), and append the following settings to the end of the file:

  "[markdown]": {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "prettier.configPath": ".prettierrc",
  "prettier.documentSelectors": ["**/*.md"],
  "prettier.prettierPath": "./node_modules/prettier/index.cjs",
  "prettier.withNodeModules": true,
  "prettier.resolveGlobalModules": true,
  "prettier.requirePragma": true

Publishing

A GitHub workflow automatically publishes the docs to https://docs.viam.com/ when new commits appear in the main branch.