gunnarsundberg / zigbee2mqtt.io

📘 Zigbee2mqtt documentation

Zigbee2MQTT.io

This repository contains the Zigbee2MQTT documentation.

It is based on VuePress v2.

Architecture

Directory-Structure:

• docgen: Some scripts to test and generate the Device-Pages.
• docs: The actual documentation.
• docs/.vuepress: Some VuePress enhancements like Stylesheets.
• public: Static assets.
• supported-devices-component: Vue.js component rendering the devices-overview page.
• navbar.ts: Configuration for the top navigation.
• sidebar.ts: Configuration for the sidebars by individual sections (like Guide).
• vuepress.config.ts: The VuePress config file.

Docgen

The docgen-scripts helps to generate and update the individual device-pages (/docs/devices/*.md). zigbee-herdsman-converters exposes a list with supported devices which is used for generation. It also updates the Devices-List used by the Supported-Devices overview page.

The ## Notes section of each page is writte by hand and does not come from zigbee-herdsman-converters. This section gets preserved and can be edited.

Docgen is written in Typescript, so you need a recent version of Node.js and NPM.

# Install dependencies
npm ci

# Run docgen
npm run docgen

Docgen Tests

Docgen includes some scripts to help testing the page.

• check-device-images: Checks for missing device images
• check-links: Checks for broken internal links

Attention: check-links iterates over the generated VuePress files, so you have to build the page first!

VuePress

# Install dependencies
npm ci

Building

# Run vuepress build
npm run build

The build-artifact gets written to dist directory.

Development

# Run vuepress in dev mode with hot-reloading
npm run dev

The dev-Mode excludes the huge amount device-pages which slows down the build process drastically. If you are interested in the device-pages you could include them by using the npm run dev:devices npm-run script.

Docker

You can also just use a docker-image include Node.js.

$ docker run --rm -v $PWD:/app -u $UID -ti node:16 bash
node@87e1438ef553:/$ cd /app
node@87e1438ef553:/app$ npm ci
node@87e1438ef553:/app$ npm run dev