Welcome to the Viam Documentation

Note

Looking to contribute? Check out the Contributor Guide. For help knowing what and how to write, check out tutorial template and our component pages.

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:

make serve-dev

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

make serve-prod

Tip

You can also run hugo serve after installing Hugo to show the production view.

Generate HTML docs

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

make build-prod

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:

brew install flake8

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:

brew 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.