This repository contains the Zigbee2MQTT documentation.
It is based on VuePress v2.
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.
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 written 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 docgenDocgen includes some scripts to help testing the page.
check-device-images: Checks for missing device imagescheck-links: Checks for broken internal links
Attention: check-links iterates over the generated VuePress files, so you have to build the page first!
Use Node.js 16 for building VuePress (other versions like Node.js 18 are not supported)
# Install dependencies
npm ci# Run vuepress build
npm run buildThe build-artifact gets written to dist directory.
# Run vuepress in dev mode with hot-reloading
npm run devThe 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.
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