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.

Continuous integration

GitHub Actions workflows run linting and link checks on every pull request, publish and sync search on merges to main, and validate code samples and SDK coverage on a weekly schedule. The table below is a quick reference; see .github/workflows/README.md for full descriptions, triggers, secrets, and known issues.

Workflow	What it does	When it runs	Blocks PR?
vale-lint.yml	Vale prose style check	Pull request	Yes
codespell.yml	Spell-check docs/	Pull request	Yes
run-htmltest-local.yml	Internal link check	Pull request	Yes
markdown-lint.yml	Markdown structure lint	Pull request	Informational
prettier-lint.yml	Prettier formatting check	Pull request, push to main	Informational
python-lint.yml	Lint Python snippets in Markdown	Pull request	Informational
pr-labeler.yml	Add safe to build label / welcome comment	PR opened	No
alias-reminder.yml	Remind authors to add redirect aliases	PR moved files	No
docs.yml	Build site, sync search index	Push to main	N/A
inkeep.yml	Sync docs source to Inkeep AI search	Push to main (docs/)	N/A
run-htmltest.yml	External link check	Tuesdays 10:00 UTC	N/A (Jira)
test-code-snippets.yml	Run Python/Go/TS code samples against live Viam	Mondays 09:00 UTC, push to samples	N/A (Jira)
check-methods.yml	Check docs coverage of SDK API methods	Wednesdays 10:00 UTC	N/A (Jira)

Note

The scheduled test-code-snippets.yml and check-methods.yml jobs run against a live Viam test organization and external SDK sites, so their results depend on that org's state and on upstream changes. See .github/workflows/README.md for details.