{"id":28425174,"url":"https://github.com/esphome/esphome-docs","last_synced_at":"2026-04-09T03:02:30.106Z","repository":{"id":37381833,"uuid":"133223461","full_name":"esphome/esphome-docs","owner":"esphome","description":"Source for esphome.io documentation files.","archived":false,"fork":false,"pushed_at":"2026-01-20T22:01:49.000Z","size":187575,"stargazers_count":413,"open_issues_count":215,"forks_count":2138,"subscribers_count":22,"default_branch":"current","last_synced_at":"2026-01-20T22:42:11.497Z","etag":null,"topics":["hacktoberfest","home-assistant","home-automation","iot","python","rst","sphinx","sphinx-doc"],"latest_commit_sha":null,"homepage":"https://esphome.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/esphome.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"custom":"https://www.openhomefoundation.org"}},"created_at":"2018-05-13T09:37:21.000Z","updated_at":"2026-01-18T13:37:11.000Z","dependencies_parsed_at":"2023-09-27T01:13:35.161Z","dependency_job_id":"9a76fae8-2199-451e-91aa-36f9707d42bf","html_url":"https://github.com/esphome/esphome-docs","commit_stats":null,"previous_names":[],"tags_count":573,"template":false,"template_full_name":null,"purl":"pkg:github/esphome/esphome-docs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esphome%2Fesphome-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esphome%2Fesphome-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esphome%2Fesphome-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esphome%2Fesphome-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/esphome","download_url":"https://codeload.github.com/esphome/esphome-docs/tar.gz/refs/heads/current","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esphome%2Fesphome-docs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28677715,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-23T01:00:35.747Z","status":"online","status_checked_at":"2026-01-23T02:00:08.296Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest","home-assistant","home-automation","iot","python","rst","sphinx","sphinx-doc"],"created_at":"2025-06-05T10:36:28.089Z","updated_at":"2026-03-03T11:03:04.273Z","avatar_url":"https://github.com/esphome.png","language":"Python","funding_links":["https://www.openhomefoundation.org"],"categories":[],"sub_categories":[],"readme":"# ESPHome-Docs\n\n[![Netlify Status][netlify-badge]][netlify-link]\n[![Discord Chat][discord-badge]][discord-link]\n[![GitHub release][github-badge]][github-link]\n\n[netlify-badge]: https://api.netlify.com/api/v1/badges/97a2e9ce-cee7-4cc8-8dc7-537c92a23fa7/deploy-status\n[netlify-link]: https://app.netlify.com/sites/esphome/deploys\n[discord-badge]: https://img.shields.io/discord/429907082951524364.svg\n[discord-link]: https://discord.gg/KhAMKrd\n[github-badge]: https://img.shields.io/github/release/esphome/esphome.svg\n[github-link]: https://github.com/esphome/esphome/releases\n\n\u003ca href=\"https://esphome.io/\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://media.esphome.io/logo/logo-text-on-dark.svg\"\u003e\n    \u003cimg src=\"https://media.esphome.io/logo/logo-text-on-light.svg\" alt=\"ESPHome Logo\"\u003e\n  \u003c/picture\u003e\n\u003c/a\u003e\n\nThis repository contains the source for the documentation site for ESPHome, built with [Astro](https://astro.build/) and [Starlight](https://starlight.astro.build/).\n\n## Project Structure\n\nThe project follows the Astro/Starlight directory structure:\n\n```text\nesphome-docs/\n├── src/\n│   ├── assets/           # Static assets (logos, etc.)\n│   ├── components/       # Astro components\n│   ├── content/\n│   │   └── docs/         # MDX documentation files\n│   ├── lib/              # Utility functions\n│   └── styles/           # CSS files\n├── public/\n│   └── images/           # Shared images (multi-use, ImgTable)\n├── astro.config.mjs      # Astro configuration\n├── tsconfig.json         # TypeScript configuration\n└── package.json          # Node.js dependencies\n```\n\n## Image File Resolution\n\nImages in the Astro/Starlight site are handled in two ways:\n\n### Imported Local Images (Single-use images)\n\nFor images used in only one document:\n\n```jsx\nimport { Image } from 'astro:assets';\nimport myImageImg from './images/my-image.jpg';\n\n\u003cImage src={myImageImg} alt=\"Description\" layout=\"constrained\" /\u003e\n```\n\n- Images are stored in a local `images/` directory next to the MDX file\n- They are imported at the top of the file\n- Astro automatically optimizes these images during build\n- Variable names follow camelCase convention with `Img` suffix\n\n### Absolute Paths (Multi-use images and ImgTable)\n\nFor images used in multiple documents or in ImgTable components:\n\n```jsx\n\u003cImage src=\"/images/shared-image.jpg\" alt=\"Description\" layout=\"constrained\" /\u003e\n```\n\n- Images are stored in `/public/images/`\n- Referenced using absolute paths starting with `/images/`\n- **Important**: All images used in ImgTable components MUST remain in `/public/images/`\n\n### ImgTable Component\n\nThe ImgTable component creates grids of component cards (commonly used on index pages):\n\n```jsx\n\u003cImgTable items={[\n  [\"Title\", \"/path/to/page/\", \"image.png\"],\n  [\"Title 2\", \"/path/to/page2/\", \"image2.png\", \"caption\"],\n  [\"Title 3\", \"/path/to/page3/\", \"image3.png\", \"caption\", \"dark-invert\"],\n]} /\u003e\n```\n\nAll images referenced in ImgTable **must** be in `/public/images/` as the component resolves them to `/images/filename.png`.\n\n## Starlight Framework\n\nThe site uses [Starlight](https://starlight.astro.build/), a documentation framework built on Astro. Key features include:\n\n- Built-in responsive design\n- Automatic dark mode support\n- Search functionality via Pagefind\n- Sidebar navigation\n- Right-hand table of contents\n- SEO optimization\n- Accessibility features\n\n## MDX Format\n\nContent is written in [MDX](https://mdxjs.com/), which allows you to use JSX components within Markdown:\n\n```mdx\n---\ntitle: \"My Page Title\"\ndescription: \"Page description for SEO\"\n---\n\nimport { Image } from 'astro:assets';\nimport myImageImg from './images/my-image.jpg';\n\n# Heading\n\nRegular Markdown content here.\n\n\u003cImage src={myImageImg} alt=\"Description\" layout=\"constrained\" /\u003e\n```\n\n## Custom Components\n\n### Astro Components\n\nCustom components are located in `src/components/` and can be imported into MDX files:\n\n- **APIRef**: Links to C++ API documentation\n- **ImgTable**: Grid of component cards with images\n- **Figure**: Images with optional captions\n- **Footer**: Custom footer component\n\n### Using Components\n\nImport and use components in MDX files:\n\n```jsx\nimport APIRef from '@components/APIRef.astro';\nimport Figure from '@components/Figure.astro';\nimport myImageImg from './images/my-image.jpg';\n\n\u003cAPIRef text=\"component.h\" path=\"component/component.h\" /\u003e\n\n\u003cFigure src={myImageImg} alt=\"Description\" caption=\"Optional caption\" /\u003e\n```\n\n## Alert Boxes\n\nUse GitHub-flavored alert syntax for callouts:\n\n```markdown\n\u003e [!NOTE]\n\u003e This is important information that readers should pay attention to.\n\n\u003e [!IMPORTANT]\n\u003e This is helpful information that readers should be aware of.\n\n\u003e [!TIP]\n\u003e Helpful advice or best practices.\n\n\u003e [!WARNING]\n\u003e Important warnings or potential issues.\n\n\u003e [!CAUTION]\n\u003e Critical cautions that could cause damage.\n```\n\n## Mathematical Expressions\n\nLaTeX equations are supported using KaTeX:\n\nInline math: `$E = mc^2$`\n\nBlock equations:\n\n```markdown\n$$\n\\text{formula} = \\frac{a}{b}\n$$\n```\n\n## Development\n\nTo run the site locally:\n\n1. Install Node.js (v18 or later recommended)\n1. Clone this repository\n1. Install dependencies: `npm install`\n1. Run development server: `npm run dev`\n1. Open your browser to `http://localhost:4321/`\n\n### Available Commands\n\n```bash\nnpm run dev          # Start development server\nnpm run build        # Build for production\nnpm run preview      # Preview production build locally\nnpm run astro        # Run Astro CLI commands\n```\n\n## Building for Production\n\n```bash\nnpm run build\n```\n\nThe built site will be in the `dist/` directory.\n\nSee the GitHub workflows in `.github/workflows` for CI/CD configuration.\n\n## Contributing\n\nContributions to improve the documentation are welcome! Please follow these steps:\n\n1. Fork the repository\n1. Create a new branch for your changes\n1. Make your changes following the conventions described above\n1. Test your changes locally with `npm run dev`\n1. Submit a pull request\n\n### Image Guidelines\n\n- Use local imported images for single-use images (one file only)\n- Keep multi-use images in `/public/images/` with absolute paths\n- All ImgTable images must remain in `/public/images/`\n- Use descriptive alt text for accessibility\n- Include `layout=\"constrained\"` for responsive images\n\n## License\n\nThe ESPHome documentation is licensed under the\n[Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License][by-ns-sa].\n\n**Documentation:** \u003chttps://esphome.io/\u003e\n\nFor issues, please go to [the issue tracker](https://github.com/esphome/esphome/issues).\n\nFor feature requests, please see [feature requests](https://github.com/orgs/esphome/discussions).\n\n[by-ns-sa]: https://creativecommons.org/licenses/by-nc-sa/4.0/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fesphome%2Fesphome-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fesphome%2Fesphome-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fesphome%2Fesphome-docs/lists"}