The documentation site for The Things Network is built with Hugo.
All content is stored as Markdown files in doc/content.
Data for generated documentation like the glossary is stored in doc/data.
The Things Network Documentation development tooling uses Go
(Hugo is pinned in go.mod and built with make deps). The theme has no JavaScript build step.
- Follow Go's installation guide to install Go.
The theme lives in doc/layouts + doc/assets (plain CSS and JS, no Bulma/TTUI). The global
header and footer render from doc/data/site_nav.json, and icons from doc/data/icons.json. Both
are generated from www.thethingsnetwork.org's single navigation source — do not edit them by
hand; re-export them from the platform repo instead:
node scripts/export-docs-chrome.mjs <path to this repo>/doc/data
Nav hrefs are root-relative and prefixed with params.ttnOrigin (default
https://www.thethingsnetwork.org); for a local all-in-one preview run Hugo with
HUGO_PARAMS_TTNORIGIN=http://localhost:3000.
Fonts, brand tokens and the page header (tn-ph) come from doc/assets/css/ttn-tokens.css and
doc/static/fonts/ttn/, also generated by the platform repo (contract: its
docs/brand-page-header.md). Re-export them after a token, font or page-header change there:
node scripts/export-brand-tokens.mjs <path to this repo>/doc/assets/css/ttn-tokens.css <path to this repo>/doc/static/fonts/ttn ../fonts/ttn
doc/assets/css/docs.css holds only the docs' own components; it uses the shared tokens and keeps
the header/footer rules identical to the website's site.css.
Every page with the left navigation opens with the page header (layouts/partials/docs/page-header.html):
breadcrumb, an eyebrow (the page's sidebar group), the title, a lede (the lead front matter, else
description) and buttons (actions front matter: label, ref or href, style, icon,
icon_before). Section landing pages can also use the chapters, feature and topics shortcodes
(see doc/content/lorawan/_index.md); a section's numbered course is its chapters front matter and
its topic index the topics front matter.
Install dependencies and tooling to help you comply with our git style guidelines by running
$ make init
You can start a development server with live reloading by running
make or make server. This command will print the address of the server.
The documentation site can be built for Github Pages by running make build.public. This will
output the site to public.
The documentation site can be built for internal (offline) use by running make build.internal. This will
output the site to internal.
Please see the style, branch naming, and commit guidelines in CONTRIBUTING
Run make new <path> to create a new documentation section from the template at path. For example, make new getting-started/hello will create a section in getting-started/hello.