Home Assistant Add-on: Homedocs

Hello Home Assistant Community.

I have created an Add-On to document anything you want with markdown.

image

Open your Home Assistant instance and show the add add-on repository dialog with a specific repository URL pre-filled.

I use it to document maintenance stuff in and around the house. Moreover I add manuals there to have it at a central place.

Please try it out and give me feedback if you find any bugs or have improvement ideas.
Easiest would be if you create a github issue.

How to use

  1. Install the addon
  2. Start the addon
  3. the addon creates a folder called homedocs in your config folder
  4. the addon copies some sample data to this folder
  5. edit the markdown files in the homedocs folder (I recommend the Studio Code Server add-on)
  6. The addon will recognize the changes and build the site
  7. open the webui to see your beautiful documentation
  8. (optional) you can open it outside of your home assistant if you have the port configured

Roadmap

  • Image optimization
  • More efficient build
  • Integrated search
  • Table of contents

Version 2.0?

The Add-on is already in version 2.0.2. This is because my first try was to use Astro Starlight, but I had problems with ingress and the build wasn’t as flexible as I want.
So I decided to rewrite everything and version it with 2.

Thanks to the projects elysia, bun, markdown-it, tailwind and daisyui and many more :slight_smile:

1 Like

Nice add-on, it’s a good idea to have something to document the HA install. Right now we “only” have Bookstack. :slight_smile:

Do you have anything planned regarding an export function like pdf or some kind of external access?
I could imagine a typical use case like HA goes down, I’m not home and my wife would like to look something up… :slight_smile:

Hi Patrick,

Thanks.
So you mean export one giant pdf for all pages or just export per page?
I havn’t planned it, but I think it is not that much effort.

Moreover you could set an external port and if just HA is down but the server is still running you can connect to it. In the next version I will also add a robots.txt that search engines won’t crawl your docs if you have it in the internet.

1 Like

In my idea it would be a complete pdf to export, so one can safe it in a Google Drive or some other space where access is possible outside of everything “homeserver”.

I do know, that this is a case, that comes up only 0.5% of the time…but that’s where one would need it the most. :slight_smile:

I can only speak for myself, but I’d be the one in my household, that would use the documentation most of the time, but if something goes wrong, either with me or the setup, my wife would need to be able to get access. That’s why I would want it to be external. :slight_smile: But that’s just me :laughing:

Ideally one could automate the build and upload to some server (the upload didn’t need to be part of the add-on).

Opening ports for HA is not my cup of tea, I’m happy with my NabuCasa remote connection, that I only enable, if I’m out of the house. :smiley:

Version 2.0.3 brings:

  • experimental /html-export endpoint
  • robots.txt to disallow all bots
  • date and time in logs

experimental /html-export endpoint

It will merge all pages into one and then you could print it to pdf with the browser.
But I think images won´t work everywhere because of their relative paths.
The build runs always when you hit the endpoint, so this can cost cpu.

But in my test I found out, that you won’t be able to call it inside ingress. I will introduce some kind of footer in the next version where the export button will be.

I should do an nightly and beta branch for such changes in the future. :slight_smile:

1 Like