Skip to content

Commit

Permalink
Merge pull request #4 from masterwendu/elysia
Browse files Browse the repository at this point in the history
2.0.0 - Elysia
  • Loading branch information
masterwendu authored May 29, 2024
2 parents 80f0b99 + 27e5b0e commit cfb9569
Show file tree
Hide file tree
Showing 68 changed files with 837 additions and 18,850 deletions.
5 changes: 5 additions & 0 deletions .vscode/extensions.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"recommendations": [
"biomejs.biome"
]
}
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ This repository contains the following add-ons
<!-- ![Supports armv7 Architecture][armv7-shield] -->
<!-- ![Supports i386 Architecture][i386-shield] -->

_Document stuff with Markdown based on Astro Starlight_
_Document stuff with Markdown_

<!--
Expand Down
2 changes: 1 addition & 1 deletion homedocs/.mise.toml
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
[tools]
node = "20"
bun = "1.1.6"
bun = "1.1.10"
6 changes: 6 additions & 0 deletions homedocs/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,11 @@
<!-- https://developers.home-assistant.io/docs/add-ons/presentation#keeping-a-changelog -->

## 2.0.0

- **BREAKING** The /config/homedocs directory doesn't need the content/docs, assets and files folder anymore. All content is now directly in the /config/homedocs folder.
- Homedocs rewritten without astro. Uses now an elysia webserver and markdown-it for rendering markdown.
- **BREAKING** Config changed and internal ports changed. I recommend to uninstall and reinstall the addon. Your markdown data will be kept in the home assistant config folder.

## 1.0.9

- Fix webserver to use correct base url
Expand Down
11 changes: 2 additions & 9 deletions homedocs/DOCS.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,19 +9,12 @@ This addon helps you document stuff around your home inside home assistant in a
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
- in the `content/docs` folder you can write your documentation
- all images should be placed in the `assets` folder
- the will be automatically optimized by astro
6. The addon will recognize the changes and build the site after a give timeout (60 seconds is default)
- the timeout is needed because the build takes some time and can just runs once in parallel.
6. The addon will recognize the changes and build the site
7. open the webui to see your beautiful documentation

### how to edit the documentation

The documentation lies in your `config` directory under `homedocs`. When you edit or add/remove the markdown files, your changes will be build after the build timeout and you will see the changes inside the webui.

__Each markdown file needs to have a frontmatter at the beginning of the file.__
Checkout the examples.
The documentation lies in your `config` directory under `homedocs`. When you edit or add/remove the markdown files, your changes will be build and you will see the changes inside the webui.

#### Use the Studio Code Server addon

Expand Down
16 changes: 4 additions & 12 deletions homedocs/Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -22,22 +22,14 @@ RUN if [[ $(uname -m) == "aarch64" ]] ; \
RUN npm install -g bun

# Copy starlight data
COPY starlight /starlight
WORKDIR /starlight
RUN bun install
COPY server /server
WORKDIR /server

# copy and setup webserver
COPY webserver/dist/index.js /webserver/index.js
COPY webserver/src/templates /webserver/templates
RUN mkdir -p /webserver/public
RUN bun install
RUN bun run build

# copy and setup run script
COPY run.sh /
RUN chmod a+x /run.sh

# Disable astro telemetry
RUN bunx astro telemetry disable

WORKDIR /webserver

CMD [ "/run.sh" ]
34 changes: 7 additions & 27 deletions homedocs/README.md
Original file line number Diff line number Diff line change
@@ -1,26 +1,17 @@
# Homedocs

With this home assistant addon you can easily create a documentation site for your home or something else.
It uses Starlight from astro under the hood.

__Why homedocs__
- Create a documentation site for your home and everything else
- Auth with home assistant
- Fast to create with markdown

__Why starlight?__

- Very good docs layout
- markdown and MDX support
- integrated search
- images are automatically optimized
- mobile optimized
- dark mode

__How I use it__:

I document stuff that I don't need very often, for example a yearly maintainance of the heating.
Moreover I printed QR codes on some devices, that you can fast access the documentation.
In my docs I also store all manual files, so I have everything in one place.

I have multiple documentation sites for:
- garden
Expand All @@ -41,30 +32,19 @@ I have multiple documentation sites for:
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
- in the `content/docs` folder you can write your documentation
- all images should be placed in the `assets` folder
- the will be automatically optimized by astro
6. The addon will recognize the changes and build the site after a give timeout (60 seconds is default)
- the timeout is needed because the build takes some time and can just runs once in parallel.
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

## Troubleshooting

### Build is not triggered

I had sometimes the issue that the build wasn't triggert, if this happens you can restart your addon, then the build will be triggert on startup.

## Check the logs!

If your made a mistake in your markdown files the build will fail, check the logs for more information. Starlight will give you a hint on what went wrong.
You won't see the error in the browser, it will still display the last version.

## Roadmap

- [ ] Build information in frontend
- I could add custom web path for build information or it will be displayed on every page as some kind of overlay
- [ ] Themes
- Starlight has a built in theme feature, I could provide some predefined themes to select from and the possibility to create custom themes
- Moreover I could get the home assistant theme and use this base colors
- [ ] hot reload
- Starlight is working on SSR, maybe it is then possible to have hot reload instead of the full build
- [ ] Image optimization
- [ ] More efficient build
- [ ] Integrated search
- [ ] Table of contents
20 changes: 6 additions & 14 deletions homedocs/config.yaml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
name: Homedocs

Check warning on line 1 in homedocs/config.yaml

View workflow job for this annotation

GitHub Actions / Lint add-on homedocs

'map' contains the 'config' folder, which has been replaced by 'homeassistant_config'. See: https://developers.home-assistant.io/blog/2023/11/06/public-addon-config
description: Document stuff with Markdown based on Astro Starlight
version: "1.0.9"
description: Document stuff with Markdown
version: "2.0.0"
slug: homedocs
init: false
url: https://github.com/masterwendu/homeassistant-addons/tree/main/homedocs
Expand All @@ -14,19 +14,11 @@ startup: services
map:
- config:rw
ingress: true
ingress_port: 4321
ingress_port: 3000
ports:
- 4321:null
3000/tcp: null
ports_description:
- 4321: "Webserver port"
ports:
4321/tcp: null
ports_description:
4321/tcp: Web interface (Not required for Ingress)
3000/tcp: Web interface (Not required for Ingress)
panel_icon: mdi:text-box-outline
panel_admin: false
options:
buildTimeoutInSeconds: 60
schema:
buildTimeoutInSeconds: int(10,)
image: "ghcr.io/masterwendu/{arch}-addon-homedocs"
# image: "ghcr.io/masterwendu/{arch}-addon-homedocs"
24 changes: 5 additions & 19 deletions homedocs/run.sh
Original file line number Diff line number Diff line change
Expand Up @@ -3,34 +3,20 @@
if [ -z "$(ls -A /config/homedocs)" ]; then
# create a directory named "homedocs" in the "/config" directory if it doesn't already exist.
mkdir -p /config/homedocs
mkdir -p /config/homedocs/assets
mkdir -p /config/homedocs/content
mkdir -p /config/homedocs/files
echo "created /config/homedocs directory."

# copy the example contents of the "/starlight/src/content/docs" directory to the "/config/homedocs" directory.
cp -r /starlight/src/content/docs /config/homedocs/content
cp -r /starlight/src/assets /config/homedocs
cp -r /starlight/public/files /config/homedocs
cp -r /server/docs/* /config/homedocs
echo "copied example content to /config/homedocs."
else
echo "/config/homedocs is not empty, skipping copy example content."
fi

rm -rf /starlight/src/content/docs
rm -rf /starlight/src/assets
rm -rf /starlight/public/files

# Link /config/homedocs with /starlight/content/docs
ln -s /config/homedocs/content/docs /starlight/src/content
ln -s /config/homedocs/assets /starlight/src
ln -s /config/homedocs/files /starlight/public

# ingress path
INGRESS_ENTRY=$(bashio::addon.ingress_entry)
# INGRESS_ENTRY=$(bashio::addon.ingress_entry)

# build timeout option
BUILD_TIMEOUT_IN_SECONDS=$(bashio::config 'buildTimeoutInSeconds')
# BUILD_TIMEOUT_IN_SECONDS=$(bashio::config 'buildTimeoutInSeconds')

# start the starlight dev server to get changes on the fly
INGRESS_ENTRY=$INGRESS_ENTRY BUILD_TIMEOUT_IN_SECONDS=$BUILD_TIMEOUT_IN_SECONDS bun index.js
# start the webserver
DOCS_BASE_PATH=/config/homedocs bun run start:production
Original file line number Diff line number Diff line change
Expand Up @@ -41,4 +41,4 @@ yarn-error.log*
package-lock.json
**/*.bun

public
dist
File renamed without changes.
26 changes: 26 additions & 0 deletions homedocs/server/biome.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
{
"$schema": "https://biomejs.dev/schemas/1.7.3/schema.json",
"organizeImports": {
"enabled": true
},
"linter": {
"enabled": true,
"rules": {
"recommended": true,
"style": {
"noUselessElse": "off",
"noNonNullAssertion": "off"
},
"correctness": {
"useJsxKeyInIterable": "off"
}
}
},
"javascript": {
"formatter": {
"semicolons": "asNeeded",
"quoteStyle": "single",
"trailingComma": "all"
}
}
}
Binary file added homedocs/server/bun.lockb
Binary file not shown.
File renamed without changes.
7 changes: 7 additions & 0 deletions homedocs/server/docs/Downloads/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
If you want to save for example some manuals you can create download links with the HTML syntax:

```html
<a href="../files/sample.pdf" download>here</a>
```

Download the file <a href="../files/sample.pdf" download>here</a>
7 changes: 7 additions & 0 deletions homedocs/server/docs/Folder/hierarchy/file.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# File in folder

I am a markdown file:

- 1. One
- 2. Two
- 3. Three
8 changes: 8 additions & 0 deletions homedocs/server/docs/Folder/hierarchy/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---

title: Subfolder

---


This is a index file in a subfolder of a folder, with a defined title so the subfolder name will be overwritten.
File renamed without changes.
Binary file added homedocs/server/docs/images/Home-Docs.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added homedocs/server/docs/images/documentation.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
13 changes: 13 additions & 0 deletions homedocs/server/docs/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
---
title: Welcome to Homedocs
---

![](./images/Home-Docs.png)

## Congrats on setting up a new Homedocs project!

Your documentation files are located in the homedocs folder inside your home assistant configuration.

## Get started writing your homedocs!

![](./images/documentation.gif)
35 changes: 35 additions & 0 deletions homedocs/server/package.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
{
"name": "server",
"version": "1.0.50",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1",
"dev": "bun run --watch src/index.ts",
"start": "bun src/index.ts",
"start:production": "NODE_ENV=production bun src/index.ts",
"build": "bun run --bun scripts/build.ts"
},
"dependencies": {
"@kitajs/html": "4.1.0",
"@kitajs/ts-html-plugin": "4.0.1",
"chokidar": "3.6.0",
"elysia": "1.0.22",
"glob": "10.4.1",
"markdown-it": "14.1.0",
"markdown-it-emoji": "3.0.0",
"zod": "3.23.8"
},
"devDependencies": {
"@biomejs/biome": "1.7.3",
"@tailwindcss/typography": "0.5.13",
"@types/chokidar": "2.1.3",
"@types/markdown-it": "14.1.1",
"@types/markdown-it-emoji": "3.0.1",
"autoprefixer": "10.4.19",
"bun-types": "1.1.10",
"cssnano": "7.0.1",
"daisyui": "4.11.1",
"postcss": "8.4.38",
"tailwindcss": "3.4.3"
},
"module": "src/index.js"
}
File renamed without changes
17 changes: 17 additions & 0 deletions homedocs/server/scripts/build.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
// import { build } from "bun"
import { buildCss } from "./tailwind"

// build css with tailwind and daisyui
await buildCss()

console.log('CSS build finished ✓')

// build the server
// TODO use optimized bun build
// await Bun.build({
// entrypoints: ['./src/index.ts'],
// outdir: './dist',
// target: 'bun',
// })

console.log('Server build finished ✓')
Loading

0 comments on commit cfb9569

Please sign in to comment.