Skip to content

Commit aac00a8

Browse files
committed
Convert to Markdown and hugo (#5242)
2 parents 4faafc7 + 80f6882 commit aac00a8

File tree

2,965 files changed

+124130
-127270
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

2,965 files changed

+124130
-127270
lines changed

.github/copilot-instructions.md

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# ESPHome Documentation AI Collaboration Guide
2+
3+
This document provides context for AI models interacting with this project.
4+
Adhering to these guidelines will promote consistency and content quality.
5+
6+
## Project Overview & Purpose
7+
8+
* **Primary Goal:** ESPHome is a system to configure microcontrollers (like ESP32, ESP8266, RP2040, and LibreTiny-based chips)
9+
using simple yet powerful YAML configuration files. It generates C++ firmware that can be compiled and flashed to
10+
these devices, allowing users to control them remotely through home automation systems.
11+
12+
This repo is the source for the primary documentation for users of ESPHome, published on [esphome.io](https://esphome.io).
13+
* **Business Domain:** Internet of Things (IoT), Home Automation.
14+
15+
## Core Technologies & Stack
16+
17+
* **Languages:** HTML, CSS, Markdown, Go templates
18+
* **Frameworks & Runtimes:** Hugo and Pagefind
19+
* **Key Libraries/Dependencies:**
20+
* **Hugo:** For building the static site.
21+
* **Pagefind:** For client-side text searching
22+
23+
## Architectural Patterns
24+
25+
See the README.md file.
26+
27+
## Branches
28+
29+
* **Current**
30+
The `current` branch represents the published documentation in sync with the latest ESPHome release.
31+
PRs may be raised against this where they contain documentation revisions only.
32+
* **Next**
33+
The `next` branch is where changes are made via PR corresponding to new features in the ESPHome code repo
34+
(esphome/esphome). When a release is made this branch is merged into current.
35+
36+
## Development & Testing Workflow
37+
38+
See the README.md file
39+
40+
## Contribution Workflow (Pull Request Process)
41+
1. **Fork:** Fork the repository.
42+
1. **Branch:** Create a new branch in your fork from the appropriate base branch (`current` or `next`.)
43+
1. **Make Changes:** Adhere to all coding conventions and patterns.
44+
1. **Test:** Use the `make live-html` command to invoke hugo in server mode for instant preview.
45+
1. **Commit:** Commit your changes. There is no strict format for commit messages.
46+
1. **Pull Request:** Submit a PR against the base branch. The Pull Request title should have a prefix of the component being worked on (e.g., `[display] Add new examples`, `[abc123] Add new component`). Pull requests should always be made with the PULL_REQUEST_TEMPLATE.md template filled out correctly.
47+
48+
## Guidelines for AI generated reviews and PR summaries
49+
50+
Avoid the use of flowery language and weasel-words that add no useful content; Keep comments concise and technically
51+
accurate - you are not writing a press release.
52+
For example instead of "Created comprehensive documentation with configuration examples and setup instructions"
53+
it is sufficient to say "Created documentation with examples and instructions".
54+
55+

.github/workflows/lint.yml

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,5 +36,3 @@ jobs:
3636
3737
- name: Lint
3838
run: python lint.py
39-
- name: html-strict
40-
run: make html-strict

.gitignore

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,19 @@
1+
public/
2+
esphome-docs
3+
.hugo_build.lock
4+
.idea
5+
/node_modules/
6+
/pagefind/
7+
/data/repo.yaml
8+
/data/anchors.json
9+
/data/automations
10+
my-secrets
11+
resources/_gen
12+
113
_build
214
.DS_Store
315

16+
.cache/
417
.python-version
518
__pycache__/
619
*.py[cod]

Makefile

Lines changed: 48 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,66 +1,61 @@
1-
ESPHOME_PATH = ../esphome
2-
ESPHOME_REF = 2025.8.0
3-
PAGEFIND_VERSION=1.1.1
4-
PAGEFIND=pagefind
5-
NET_PAGEFIND=../pagefindbin/pagefind
1+
.PHONY: clean live-html check-links anchors production convert-from-rst convert-branch-in-place directories netlify repo-data all
62

7-
.PHONY: pagefind build-html html html-strict cleanhtml deploy help live-html live-pagefind Makefile netlify netlify-dependencies svg2png copy-svg2png minify
3+
SHELL := bash
4+
.SHELLFLAGS := -euo pipefail -c
85

9-
html: pagefind
10-
sphinx-build -M html . _build -j auto -n $(O) -Dhtml_extra_path=_redirects,_pagefind
116

12-
pagefind:
13-
sphinx-build -M html . _build -j auto -n $(O)
14-
mkdir -p _pagefind/pagefind
15-
${PAGEFIND}
7+
PAGEFIND=npx --yes [email protected]
168

17-
live-html: pagefind
18-
sphinx-autobuild . _build -j auto -n $(O) --host 0.0.0.0 -Dhtml_extra_path=_redirects,_pagefind
9+
export HUGO_PARAMS_COMMIT_HASH=$(shell git rev-parse --short HEAD)
10+
export HUGO_PARAMS_COMMIT_TITLE=$(shell git log -1 --pretty=%s)
11+
export HUGO_PARAMS_BRANCH=$(shell git branch --show-current)
12+
export HUGO_PARAMS_REPO_URL=$(shell git config --get remote.origin.url)
1913

20-
html-strict:
21-
sphinx-build -M html . _build -W -j auto -n $(O)
14+
all: production
2215

23-
minify:
24-
minify _static/webserver-v1.js > _static/webserver-v1.min.js
25-
minify _static/webserver-v1.css > _static/webserver-v1.min.css
16+
production: anchors
17+
hugo --minify
18+
$(PAGEFIND)
19+
hugo --minify
2620

27-
cleanhtml:
28-
rm -rf "_build/html/*"
21+
directories:
22+
mkdir -p data public pagefind content static
2923

30-
svg2png:
31-
python3 svg2png.py
24+
check-links: anchors
25+
hugo --environment production
3226

33-
help:
34-
sphinx-build -M help . _build $(O)
27+
anchors: repo-data
28+
$(PAGEFIND) -s pagefind-bootstrap
29+
hugo --environment anchors
30+
python3 script/md_anchors.py
3531

36-
net-html:
37-
sed -i 's@{{API_DOCS_URL}}@'"${API_DOCS_URL}"'@' _redirects
38-
sphinx-build -M html . _build -j auto -n $(O)
39-
mkdir -p _pagefind/pagefind
40-
${NET_PAGEFIND}
41-
sphinx-build -M html . _build -j auto -n $(O) -Dhtml_extra_path=_redirects,_pagefind
32+
repo-data: directories
33+
mkdir -p data/automations
34+
curl -s -S https://data.esphome.io/release/automations.json | script/collate_automations.sh > data/automations/current.json
35+
curl -s -S https://data.esphome.io/beta/automations.json | script/collate_automations.sh > data/automations/beta.json
36+
curl -s -S https://data.esphome.io/dev/automations.json | script/collate_automations.sh > data/automations/next.json
4237

43-
pagefind-binary:
44-
mkdir -p ../pagefindbin
45-
curl -o pagefind.tar.gz https://github.com/CloudCannon/pagefind/releases/download/v$(PAGEFIND_VERSION)/pagefind-v$(PAGEFIND_VERSION)-x86_64-unknown-linux-musl.tar.gz -L
46-
tar xzf pagefind.tar.gz
47-
rm pagefind.tar.gz
48-
mv pagefind ${NET_PAGEFIND}
49-
50-
51-
copy-svg2png:
52-
cp svg2png/*.png _build/html/_images/
53-
54-
netlify: pagefind-binary net-html copy-svg2png
55-
56-
lint: html-strict
57-
python3 lint.py
38+
live-html: anchors
39+
$(PAGEFIND)
40+
hugo server --bind 0.0.0.0 --baseURL http://localhost:1313
5841

5942
clean:
60-
rm -rf _pagefind/
61-
sphinx-build -M clean . _build $(O)
62-
63-
# Catch-all target: route all unknown targets to Sphinx using the new
64-
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
65-
%: Makefile
66-
sphinx-build -M $@ . _build $(O)
43+
rm -rf public/*
44+
rm -rf pagefind/*
45+
rm -rf data/automations/
46+
rm -rf data/repo.yaml
47+
rm -rf resources/_gen
48+
hugo mod clean
49+
50+
convert-branch-in-place:
51+
sh script/migrate.sh
52+
53+
54+
netlify: repo-data
55+
$(PAGEFIND) -s pagefind-bootstrap
56+
hugo --environment anchors
57+
python3 script/md_anchors.py
58+
hugo --minify
59+
$(PAGEFIND)
60+
# rerun hugo to incorporate generated index
61+
hugo --minify

0 commit comments

Comments
 (0)