Repository files navigation

This repository contains source for the documentation site for ESPHome.

The project follows a standard directory structure:

esphome-docs/├── archetypes/        # Content templates├── assets/            # Source files for CSS, JS, etc.├── content/           # Markdown content files├── data/              # Data files for templates├── layouts/           # HTML templates├── static/            # Static files│   └── images/        # Image files├── themes/            # Custom theme for ESPHome│   └── esphome-theme/ # The ESPHome custom theme├── hugo.yaml          # Hugo configuration└── README.md          # This file

Images in the Hugo site referred to inimg shortcodes are handled using a specific search strategy:

• When using relative paths in theimg shortcode (e.g.,{{< img src="dht22.jpg" >}}),Hugo will first look in a localimages/ subdirectory.For example, an image referenced incontent/components/sensor/dht.md will first besearched for incontent/components/sensor/images/.

• If the image is not found in the local directory, Hugo will then look in the global/static/images/ directory.

When using absolute paths (starting with/), Hugo will look directly in the specified locationrelative to the/static/ directory.

This strategy allows component documentation to have its own images while also supporting shared images across the site.

The site uses a custom theme calledesphome-theme which is designed to match the look and feel of the originalESPHome documentation. The theme includes:

• Responsive design for mobile and desktop
• Dark mode support
• Custom shortcodes for documentation features
• Navigation sidebar
• Search functionality

Hugo uses Markdown files as input. The Markdown processor in use is Goldmark.

Hugo uses a templating system to generate HTML from Markdown content. Understanding the following concepts is helpfulwhen working with or modifying the theme:

Templates are HTML files with Go templating syntax that define the structure and layout of pages. Hugo uses differenttypes of templates:

• Base Templates: Define the overall structure of the site (found inlayouts/_default/baseof.html)
• List Templates: Used for section pages that list multiple content items
• Single Templates: Used for individual content pages
• Home Template: Specifically for the homepage

Templates use blocks (like{{ block "main" . }}{{ end }}) that can be overridden by other templates.

Partials are reusable template components that can be included in other templates. They help maintain DRY (Don't RepeatYourself) code by extracting common elements:

{{ partial "header.html" . }}

The dot (.) passes the current context to the partial. Partials are stored in thelayouts/partials/ directory.

Shortcodes are special tags you can use within Markdown content to insert complex elements or custom HTML.They bridge the gap between the simplicity of Markdown and the need for more complex formatting.

{{< shortcode-name param1="value" param2="value" >}}

Shortcodes can be self-closing or can wrap content:

{{< shortcode-name >}}  Content to be processed{{< /shortcode-name >}}

Shortcode templates are stored in thelayouts/shortcodes/ directory.

Hugo has a number ofbuilt-in shortcodes and the ESPHome themealso defines several custom shortcodes:

Creates an HTML anchor point that can be linked to with fragment identifiers.

{{< anchor "my-anchor-id" >}}

NOTE: Headings automatically create anchors, so it is not necessary to insertanchor shortcodes for them.

Creates a collapsible section with a title that can be clicked to show/hide content.

{{< collapse true >}}This content will be hidden by default and can be expanded by clicking the header.You can include any Markdown content here, including lists, code blocks, etc.the parameter, if present and set to true, will have the content initially opened. Note that False is a truthy string, not a boolean{{< /collapse >}}

Creates a link to another page in the documentation with proper handling of anchors.

{{< docref "/components/sensor/dht" >}}                     <!-- Uses the target page title as link text -->{{< docref "/components/sensor/dht" "DHT Sensor Guide" >}}  <!-- Uses custom text for the link -->{{< docref "/components/sensor/dht#configuration" >}}       <!-- Links to a specific anchor on the page -->

Displays an image with optional caption, width, height, and CSS class.

{{< img src="example.jpg" alt="Example image" caption="This is an example" width="500" >}}

Creates a component card with an image, title, and optional description that links to another page.

  {{< imgtable >}}  Title 1, path/to/page1, image1.png  Title 1, path/to/page1, image1.png, "sub-caption"  Title 2, path/to/page2, image2.png, dark-invert  Title 2, path/to/page2, image2.png, "sub-caption", dark-invert  {{< /imgtable >}}

Adds SEO metadata tags to the page for better search engine optimization and social media sharing.

{{< seo description="Detailed guide for setting up the DHT sensor with ESPHome" image="dht-sensor.jpg" >}}

Creates a link to a C++ API header file.

{{< apiref "Component" "esphome/core/component.h" >}}

Creates a link specifically to a C++ class in the API documentation.

{{< apiclass "ClimateDevice" "esphome::climate::ClimateDevice" >}}{{< apiclass "WiFiComponent" "esphome::wifi::WiFiComponent" >}}

Creates a link specifically to a C++ struct in the API documentation.

{{< apistruct "SensorStateClass" "esphome::sensor::SensorStateClass" >}}{{< apistruct "GPIOOutputPin" "esphome::output::GPIOOutputPin" >}}

Creates an input field with a randomly generated API key and a copy button.

{{< api-key-input >}}

Creates a link to a GitHub user profile.

{{< ghuser name="octocat" >}}                <!-- Links to @octocat -->{{< ghuser name="octocat" text="GitHub" >}}  <!-- Links to @octocat but displays "GitHub" -->

Reads a file from the static directory and inserts it as HTML.

{{< html_file file="example.html" >}}

Creates an option block for documenting command-line options or configuration parameters.

{{< option "--help|-h" >}}This is the help option.{{< /option >}}

Creates a link to a GitHub pull request.

{{< pr number="123" >}}                <!-- Links to esphome/esphome#123 -->{{< pr number="123" repo="esphome-docs" >}}    <!-- Links to esphome/esphome-docs#123 -->

Creates a page that automatically redirects to another URL.

{{< redirect url="/some/path" >}}

Creates a note blockquote/alert box to highlight important information.

>[!NOTE]>This is important information that the reader should pay attention to.>You can include**Markdown** formatting within the block.

Creates an important blockquote/alert box to highlight helpful information.

>[!IMPORTANT]>This is helpful information that the reader should be aware of.>You can include**Markdown** formatting within the block.

Creates a tip blockquote/alert box to highlight helpful advice or best practices.

>[!TIP]>For best results, place the sensor away from heat sources.>You can include**Markdown** formatting within the block.

Creates a warning blockquote/alert box to highlight important warnings or potential issues.

>[!WARNING]>Incorrect wiring may damage your device. Double-check connections before powering on.>You can include**Markdown** formatting within the block.

Creates a caution blockquote/alert box to highlight important cautions or potential issues.

>[!CAUTION]>Incorrect wiring may damage your device. Double-check connections before powering on.>You can include**Markdown** formatting within the block.

A Python script is included to help with the conversion process from RST:

script/convert_rst_to_md.py - Converts Sphinx RST files to Hugo Markdown formatAvailable options for convert_rst_to_md.py:

positional arguments:  input_dir             Input directory containing RST files  output_dir            Output directory for Markdown filesoptional arguments:  --single FILENAME     Process a single file (relative to input_dir)  --no-images           Skip image processing

The script performs the following operations:

• Builds an anchor map to maintain internal links
• Converts RST formatting to Markdown
• Processes special directives like notes, warnings, and tips
• Converts RST tables to Markdown format
• Handles image references and copies images to appropriate locations
• Processes inline markup and references

See thescript/convert-pr.sh script for converting a PR that was written with RST.

To run the site locally:

1. Install Hugo:https://gohugo.io/installation/
2. Install NodeJS (simplest way to run pagefind)
3. Clone this repository
4. Navigate to the repository directory
5. Runmake live-html
6. Open your browser tohttp://localhost:8000/

See the GitHub workflows in.github/workflows

The built site will be in thepublic directory.

Contributions to improve the documentation are welcome! Please follow these steps:

1. Fork the repository
2. Create a new branch for your changes
3. Make your changes
4. Submit a pull request

The ESPHome documentation is licensed under theCreative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.

Documentation:https://esphome.io/

For issues, please go tothe issue tracker.

For feature requests, please seefeature requests.