Documentation
This is a placeholder page that shows you how to use this template site.
This section is where the user documentation for your project lives - all the information your users need to understand and successfully use your project.
For large documentation sets we recommend adding content under the headings in this section, though if some or all of them don’t apply to your project feel free to remove them or add your own. You can see an example of a smaller Docsy documentation site in the Docsy User Guide, which lives in the Docsy theme repo if you’d like to copy its docs section.
Other content such as marketing material, case studies, and community updates should live in the About and Community pages.
Find out how to use the Docsy theme in the Docsy User Guide. You can learn more about how to organize your documentation (and how we organized this site) in Organizing Your Content.
1 - Overview
Here’s where your user finds out if your project is for them.
This is a placeholder page that shows you how to use this template site.
The Overview is where your users find out about your project. Depending on the size of your docset, you can have a separate overview page (like this one) or put your overview contents in the Documentation landing page (like in the Docsy User Guide).
Try answering these questions for your user in this page:
What is it?
Introduce your project, including what it does or lets you do, why you would use it, and its primary goal (and how it achieves it). This should be similar to your README description, though you can go into a little more detail here if you want.
Why do I want it?
Help your user know if your project will help them. Useful information can include:
- What is it good for?: What types of problems does your project solve? What are the benefits of using it?
- What is it not good for?: For example, point out situations that might intuitively seem suited for your project, but aren’t for some reason. Also mention known limitations, scaling issues, or anything else that might let your users know if the project is not for them.
- What is it not yet good for?: Highlight any useful features that are coming soon.
Where should I go next?
Give your users next steps from the Overview. For example:
2 - Tutorials
Tutorials over verschillende onderwerpen.
This is a placeholder page that shows you how to use this template site.
Tutorials are complete worked examples made up of multiple tasks that guide the user through a relatively simple but realistic scenario: building an application that uses some of your project’s features, for example. If you have already created some Examples for your project you can base Tutorials on them. This section is optional. However, remember that although you may not need this section at first, having tutorials can be useful to help your users engage with your example code, especially if there are aspects that need more explanation than you can easily provide in code comments.
2.1 - Home Assistant
Alles Home Assistant gerelateerd.
This is a placeholder page that shows you how to use this template site.
2.1.1 - Home Assistant Automation voorbeelden
Home Assistant Automation voorbeelden.
This is a placeholder page that shows you how to use this template site.
2.1.1.1 - Garage poort met motion sensor
Controleren of de garage poort open staat terwijl er niemand aanwezig is.
Dit automation voorbeeld werkt op basis van een deursensor in combinatie met een bewegingsmelder.
De use case
De garage poort bij mij thuis kan via de Home Assistant app geopend en gesloten worden. Dit heb ik gedaan via het doorbell project van Frenck https://frenck.dev/diy-smart-doorbell-for-just-2-dollar/#1-smart-doorbell-stuff-youll-need. Het is daarmee zo makkelijk geworden om de poort via de app te bedienen dat de kinderen vaak meteen doorlopen, in de app op sluiten klikken en eigenlijk niet controleren of de poort ook wel echt dicht gaat. Daarom wil ik een repeterende melding krijgen zolang de poort open staat, tenzij er nog iemand in de garage aanwezig is.
De componenten die ik hiervoor gebruik zijn twee op zigbee gebaseerde devices:
- een deursensor SONOFF SNZB-04 via zigbee en ZHA gekoppeld
- een Xiaomi Human Body Sensor ook via zigbee en ZHA gekoppeld.
De Xiaomi sensor heeft een eigen time-out van 2 minuten. D.w.z. dat als deze 2 minuten lang geen beweging meer gedecteerd heeft, dan schakelt deze van ON naar OFF. Die ingebouwde time-out schijn je aan te kunnen passen via een hack, maar dit heb ik niet geprobeerd omdat voor mij de 2 minuten prima zijn.
Essentieel is dat de melding blijft herhalen totdat de poort dicht is.
Wanneer moet er een trigger zijn?
Soms helpt het om even in een simpele tabel te zetten, wanneer er wat moet gebeuren. In mijn geval heb ik twee devices (poort en motion) die een status kunnen hebben:
| Motion | Geen Motion |
---|
Poort Open | niks | melding |
Poort dicht | niks | niks |
Dus alleen als “Poort Open” EN “Geen Motion” dan wil ik een melding krijgen en anders geen actie uitvoeren.
Het script
Het script begint natuurlijk op de standaard manier met een alias en een omschrijving:
alias: Garagepoort staat open zonder beweging
description: Verstuur een melding als de garagepoort te lang open staat.
Eerst had ik de automation zo gemaakt dat de trigger de schakeling van de motion sensor naar off was en als condition van de poort open was, er dan een melding volgt. Maar daar zit een denkfout in, want stel nu dat de poort geopend wordt zonder dat iemand door de sensor loopt, bijvoorbeeld per ongeluk in de app de poort openklikken, dan wordt de motion off nooit getriggerd en volgt er dus nooit een melding.
Er moet dus een continue check zijn op de status van de twee sensoren. Hiervoor kun je een time_pattern https://www.home-assistant.io/docs/automation/trigger/#time-pattern-trigger gebruiken. Voor het time_pattern stel je een tijd in uren, minuten, seconden in. Dit is niet de tijd van de cyclus, maar is meer een cron tijd check. Dus seconds: “15” triggert elke keer dat de huidige tijd op 15 seconden staat en dus NIET elke 15 seconden. Ik kies er voor om in mijn automation op 30 seconden een controle te doen.
trigger:
- platform: time_pattern
seconds: '30'
hours: '*'
minutes: '*'
Wanneer dan de trigger plaatsvindt, dan moeten er dus twee condities gecheckt worden. De garagepoort moet open staan, dus ON en de motion sensor moet geen beweging zien, dat is status OFF. Dit kan via een AND condition:
condition:
- condition: state
entity_id: binary_sensor.garagepoort
state: 'on'
- condition: and
conditions:
- condition: state
entity_id: binary_sensor.lumi_sensor_motion_garage
state: 'off'
Vervolgens plakken we er een actie aan. Zelf test ik meestal via Telegram notificaties:
action:
- service: notify.telegram
data:
message: De garagepoort is open zonder beweging.
mode: single
En zo stond er nooit meer een garage poort te lang open.
2.1.2 - Home Assistant installeren
Hoe installeer je Home Assistant.
This is a placeholder page that shows you how to use this template site.
2.1.2.1 - Home Assistant VM disk resize
Resize van de virtuele disk van de Home Assistant OS VM.
Disk uitbreiding van de Home Assistant OS VM
Disk vol
Naar mate je Home Assistant meer en meer gebruikt en er ook meer logging in geschreven wordt, data van sensoren bewaard wordt, kan het gebeuren dat Home Assistant opeens klaagt over ruimte gebrek. Je ziet dan bijvoorbeeld deze melding in de logs:
'HomeAssistantCore.update' blocked from execution, not enough free space (0.8GB) left on the device
Wanneer je Home Assistant OS draait in een VM, is de oplossing gelukkig heel simpel:
- Resize de disk
- Herstart Home Assisant OS.
Resizen van de disk
Wanneer je gebruik maakt van VMware ESXi of Hyper-V, dan selecteer je de VM, gaat naar de eigenschappen van de disk en vergroot de disk naar de nieuwe waarde. Wanneer je nu Home Assistant herstart, zal deze automatisch de nieuwe disk size herkennen en de partitie vergroten tot de nieuwe maximale grootte.
Gebruik je ProxMox dan voltstaat het om op de command line de uitbreiding op te geven middels qm resize <vmid> <disk> <size>
. Wil je bijvoorbeeld van 16GB naar 24GB, dan doe je dat via het volgende commando: qm resize 100 virtio0 +8G
. Ook nu voer je een reboot uit van Home Assistant OS voor automatische resize van de partitie.
Controle
Om te controleren of de nieuwe disksize goed verwerkt is, log je in op de console van de Home Assistant OS VM. Login met de user root, er wordt geen wachtwoord gevraagd.
Type nu login
om op de command line te komen en controleer dan via fdisk -l
of de disk de nieuwe grootte heeft en of /dev/sda8 op een paar MB na, ook de nieuwe grootte heeft.
2.1.2.2 - HA - Proxmox
Hoe installeer en configureer je Home Assistant op Proxmox
⚠️ Ons advies is altijd de officiële installatie instructies op de site van Home Assistant te volgen https://www.home-assistant.io/hassio/
2.1.2.3 - HA - Raspberry Pi
Hoe installeer en configureer je Home Assistant op een Raspberry Pi
⚠️ Ons advies is altijd de officiële installatie instructies op de site van Home Assistant te volgen https://www.home-assistant.io/hassio/
2.1.2.4 - HA - Synology NAS
Hoe installeer en configureer je Home Assistant op een Synology NAS
⚠️ Ons advies is altijd de officiële installatie instructies op de site van Home Assistant te volgen https://www.home-assistant.io/hassio/
2.2 - Proxmox
Alles proxmox gerelateerd.
This is a placeholder page that shows you how to use this template site.
2.2.1 - Proxmox installeren
Hoe installeer en configureer je Proxmox
⚠️ PLACEHOLDER
⚠️ PLACEHOLDER
PLACEHOLDER om naar te verwijzen in andere docs.
2.3 - Linux
Alles Linux gerelateerd.
This is a placeholder page that shows you how to use this template site.
2.3.1 - Hoe voeg je een nieuwe (virtuele) hard drive toe
Hoe voeg je aan een linux een hard drive toe welke bij een reboot gemount blijft.
⚠️ PLACEHOLDER
⚠️ Deze tutorial is getest op Ubuntu 18.04 & 20.04 en Raspberry Pi OS (voorheen Rasbian!)
2.4 - Netwerk
Alles Netwerk gerelateerd.
This is a placeholder page that shows you how to use this template site.
2.5 - Node-RED
Alles Node-RED gerelateerd.
This is a placeholder page that shows you how to use this template site.
2.6 - Device Hacks
Tutorial Sectie voor Devices
This is a placeholder page that shows you how to use this template site.
Dit onderdeel is voor het gebruik van Tutorials die te maken hebben Devices hacks
- Zoals Shelly, Roborock etc.
2.6.1 - RoboRock S5 Max in HA zonder root
Installatie van RoboRock S5 Max stofzuiger in Home Assistant zonder rooting van de stofzuiger.
LET OP: Deze tutorial is gebaseerd op RoboRock S5 Max firmware 01.10.26 en Home Assistant OS 2020.12.1 en uitgevoerd op MacOS.
Gebruikte bronnen
Home Assistant Vacuum integratie: https://www.dutchdomotics.info/docs/tutorials/roborock-s5-max-homeassistant-zonder-root/
Gain root on BlueStacks: https://android.stackexchange.com/questions/224119/how-to-gain-root-on-bluestacks-android-emulator
Github Repository: https://github.com/89jd/hass-roborock
BlueStacks Android emulator: https://www.bluestacks.com/
⚠️ Dit is geen volledige Home Assistant ondersteunde integratie, maak altijd backups voor je begint.
Globale stappen
Om de RoboRock S5 Max stofzuiger via Home Assistant te bedienen is de “Hass-RoboRock” custom component nodig. Deze praat via Tuya tegen de stofzuiger. Om via Tuya te kunnen praten, zijn de “localKey” en “devID” nodig. Deze keys kunnen we achterhalen via de android app op de telefoon en rooting van die telefoon, maar veel makkelijker is het om de BlueStacks Android Emulator op je PC of Mac te installeren. Via die emulator kunnen we dan makkelijk root rechten krijgen en vervolgens installatie van de RoboRock Android app in BlueStacks en dan exporteren van de beide keys. Als de keys eenmaal geexporteerd zijn, hebben we BlueStacks niet meer nodig.
De tweede fase is dan het opnemen van de “Hass-RoboRock” custom component in HA met behulp van de beide keys, gevolgd door het aanmaken van een paar mooie dasboard cards.
Installatie BlueStacks
Eerste stap is de installatie van BlueStacks. Download BlueStacks via https://www.bluestacks.com/download.html en installeer de applicatie. Standaard werkt BlueStacks met een virtuele machine en de virtuele android machine (android.vbox) heeft na installatie de root disk beveiligd tegen schrijven. Aangezien we later in de procedure hier wel naar toe schrijven, moeten we deze disken op Read/Write zetten.
In MacOS open een terminal venster en edit de file: “~/Library/BlueStacks/Android/Android.vbox”. In deze file zie je een aantal entries voor HardDisk staan. Pas het type aan naar “Normal”.
<MediaRegistry>
<HardDisks>
<HardDisk uuid="{4da0cf19-7a5d-474d-9748-2c31c11fbbd6}" location="fastboot.vdi" format="VDI" type="Normal"/>
<HardDisk uuid="{fca296ce-8268-4ed7-a57f-d32ec11ab304}" location="Root.vdi" format="VDI" type="Normal"/>
<HardDisk uuid="{a9d1a5d3-cd0c-4169-9284-69b19f57b517}" location="Data.vdi" format="VDI" type="Normal"/>
</HardDisks>
</MediaRegistry>
Sla de wijzigingen op, laat je terminal window nog even open, daar komen we dadelijk nog terug. In MacOS start BlueStacks en volg onderstaande stappen:
- In BlueStacks installeer je de RoboRock app via de playstore
- Log in de RoboRock app in met hetzelfde account als de RoboRock app op je telefoon. Je moet nu je stofzuiger ook in BlueStacks kunnen zien.
- In de BlueStacks app enable je de Android Debug Bridge (ADB) via BlueStacks Preferences -> Perferences.
- In je MacOS terminal ga je naar de BlueStacks directory via:
cd /Applications/BlueStacks.app/Contents/MacOS
- Switch naar root user in je MacOS terminal:
- Download nu de SuperSU zip file waarmee in BlueStacks SuperUser rechten verkregen worden:
sudo curl https://supersuroot.org/downloads/SuperSU-v2.82-201705271822.zip -o SuperSU-v2.82-201705271822.zip
- Met het volgende commando starten we de ADB (Android Debug Bridge) en wordt een verbinding naar BlueStacks mogelijk:
- Controleer of er een device emulator online is gekomen:
Hier zie je nu de emulator connectie van BlueStacks. Soms moet je een aantal keren proberen. Je kunt de ADB server stoppen via “kill-server” en dan weer opnieuw starten en kijken of BlueStacks nu wel in de devices beschikbaar komt.
- Vervolgens uploaden we de SuperUser zip naar de virtuele SDcard in BlueStacks:
./adb push ./SuperSU-v2.82-201705271822.zip /mnt/sdcard
- Dan openen we een shell naar BlueStacks zodat we in BlueStacks op de command line uitkomen:
- Middels de volgende commando’s wordt nu de SuperUser zip uitgepakt en geinstalleerd:
# Switch naar root via de BlueStacks binary:
system/xbin/bstk/su
# Disable SELinux
setenforce 0
# Opnieuw mounten van de disken in RW mode:
mount -o rw,remount,rw /
mount -o rw,remount,rw /system
mount -o rw,remount,exec,rw /storage/emulated
# Unzip SuperSU zip
cd /mnt/sdcard
mkdir supersu
cd supersu
unzip ../SuperSU-v2.82-201705271822.zip
# Kopieren van het su commando en installatie vna su:
cp x64/su /system/xbin/su
chmod a+rwx /system/xbin/su
/system/xbin/su --install
# Start su daemon mode
/system/xbin/su --daemon
- In BlueStacks is nu de SU daemon geinstalleerd. Waarschijnlijk is de BlueStacks sessie vastgelopen en moet je bluestacks opnieuw opstarten.
- Na opnieuw starten van BlueStacks zoek je de SuperSU in BlueStacks op en Controleer of deze actief is.
- switch naar de MacOS terminal en start opnieuw de shell op en switch naar su. Het kan zijn dat je weer eerst stap 7 & 8 moet uitvoer om BlueStacks in de device emulator te zien.
Er verschijnt nu de melding: “ADB Shell has been granted.”. Dit bewijst dat je root user op de emulator geworden bent.
- We gaan nu naar de lokatie van de RoboRock app in BlueStacks om daar via het uitlezen van een cache file achter de localKey en devID te komen:
cd /data/data/com.roborock.smart/files/rr_cache
find . | egrep rr_tuya_[0-9]
- De filenaam van stap 15 is de file die de tuya informatie bevat. Deze file kopieren we naar de virtuele SDCard:
cp rr_tuya_59533 /mnt/sdcard
- Sluit de ADB Shell sessie af via CTRL+D en download de tuya file van de SDcard naar je lokale MacOS, uitpakken en vervolgens de file openen:
./adb pull /mnt/sdcard/rr_tuya_595287 /tmp/token.gz
cd /tmp
gzip -d token.gz
vi token
- Zoek in deze file naar “localKey” en “devID”. Noteer de keys die hier achter staan, bijvoorbeeld:
"localKey":"78215e844dc09e53"
"devId":"bf943b226c5bc35b22mdko"
Configuratie in Home Assistant
In Home Assistant ga je naar HACS, dan naar integrations en klik rechtsboven op het menu. Kies custom Repositories en plak de volgende URL en kies category integration:
https://github.com/89jd/hass-roborock
Herstart Home Assistant.
Om de stofzuiger zichtbaar te krijgen, heeft deze de NPM module nodig die normaal niet in Home Assistant zit. Om deze te installeren op een HA OS gebaseerde installatie, op je de homeassistant container (ik gebruik hier portainer voor) en run het commando:
apk add --update nodejs npm
Deze actie moet je na elke stop en start van de home assistant container doen. Niet bij de standaard “restart”. Er zijn ook methodes om dit ook nog te automatiseren, zie bijvoorbeeld https://community.home-assistant.io/t/custom-component-roborock-communication/229032/34, maar die heb ik niet verder onderzocht omdat ik nog te onervaren ben in Home Assistant en wil voorkomen dat ik de container permanent beschadig.
Wanneer je nu in HA naar de HA integrations gaat (dus niet HACS), kun je daar de RoboRock integratie toevoegen. Deze vraagt vervolgens om de naam, IP, localKey en devID. De naam die je hier in vult is de naam zoals deze straks als entity beschikbaar komt. In het voorbeeld heb ik als naam “roborock s5 max” gebruikt, wat later zichtbaar is als “roborock_s5_max” als entity.
Ga in HA naar configuration -> entities. The RoboRock verschijnt hier nu als een entity.
Aansturen RoboRock
Om de RoboRock aan te sturen heb je nu de beschikking over een aantal services die je kunt aanroepen. Deze staan uitvoerig beschreven in https://www.home-assistant.io/integrations/vacuum/. Om te testen of de RoboRock aan te sturen is, ga je naar HA -> Developer Tools -> Services. Kies hier de service “vacuum.start” en als service data:
entity_id: vacuum.roborock_s5_max
Als je nu op “Call Service” klikt, moet de RoboRock al gaan beginnen. Dit is het bewijs dat de integratie gelukt is.
Kamers in RoboRock aanduiden
Via de RoboRock app kun je een enkele of meerdere rooms aanduiden om te stofzuigen. Als je dit vanuit Home Assistant wilt doen, dan worden deze aangeduid als segmenten. Momenteel is er nog geen mogelijkheid om de segmenten die beschikbaar zijn uit te lezen, dus zul je moeten testen welke segment ID overeenstemt met welke kamer. De segment IDs beginnen vanaf id 15.
Ga weer naar HA -> Developer Tools -> Services en selecteer “roborock.vacuum_clean_segment”. Voor de service data vul je in:
segments:
- 15
entity_id: vacuum.roborock_s5_max
Voordat je op “Call Service” klikt, open je de RoboRock App en kijk naar de plattegrond. Klik nu op “call service”. Hopelijk springt de RoboRock nu aan en zie je na enkele seconden in de App de kamer kleuren die gezogen gaat worden. Op deze manier test je dus kamer voor kamer, tot je ze allemaal gevonden hebt.
Wil je later in een automation meerdere segmenten aanspreken, dan kan dit als volgt:
2.7 - Docker
Tutorial Sectie voor Docker en Docker-Compose
This is a placeholder page that shows you how to use this template site.
Dit onderdeel is voor het gebruik van Tutorials die te maken hebben met docker en Docker-Compose
2.7.1 - Docker + Docker-Compose
Docker samen met Docker-Compose installeren.
⚠️ Controleer altijd het script voordat je het installeert!
⚠️ Deze tutorial is gebaseerd op Ubuntu 18.04 & 20.04!
Volledige documentatie installatie Docker
Docker: https://docs.docker.com/engine/install/ubuntu/
Docker-compose: https://docs.docker.com/compose/install/
Docker
Eerst installeren we Docker d.m.v. het convenience script.
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
Voeg je user toe aan de “docker” group zodat je niet elke keer sudo hoeft in te typen.
sudo usermod -aG docker <user>
Docker-Compose
Daarna installeren we Docker-Compose. (⚠️ let op de versie hieronder kan verouderd zijn, ga naar de link bovenin het artikel voor de nieuwste versie ⚠️ )
sudo curl -L "https://github.com/docker/compose/releases/download/1.27.4/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose
Test de instalatie:
Als je output lijkt op docker-compose version 1.27.4, build 01110ad01
zit je goed.
🎉🎉🎉
Gefeliciteerd! Je hebt nu Docker en Docker-Compose draaien en bent klaar voor de mooie wereld van het selfhosten.
🎉🎉🎉
2.8 - Multi-Bear Domicile Setup
A short lead description about this content page. It can be bold or italic and can be split over multiple paragraphs.
This is a placeholder page. Replace it with your own content.
Text can be bold, italic, or strikethrough. Links should be blue with no underlines (unless hovered over).
There should be whitespace between paragraphs. Vape migas chillwave sriracha poutine try-hard distillery. Tattooed shabby chic small batch, pabst art party heirloom letterpress air plant pop-up. Sustainable chia skateboard art party banjo cardigan normcore affogato vexillologist quinoa meggings man bun master cleanse shoreditch readymade. Yuccie prism four dollar toast tbh cardigan iPhone, tumblr listicle live-edge VHS. Pug lyft normcore hot chicken biodiesel, actually keffiyeh thundercats photo booth pour-over twee fam food truck microdosing banh mi. Vice activated charcoal raclette unicorn live-edge post-ironic. Heirloom vexillologist coloring book, beard deep v letterpress echo park humblebrag tilde.
90’s four loko seitan photo booth gochujang freegan tumeric listicle fam ugh humblebrag. Bespoke leggings gastropub, biodiesel brunch pug fashion axe meh swag art party neutra deep v chia. Enamel pin fanny pack knausgaard tofu, artisan cronut hammock meditation occupy master cleanse chartreuse lumbersexual. Kombucha kogi viral truffaut synth distillery single-origin coffee ugh slow-carb marfa selfies. Pitchfork schlitz semiotics fanny pack, ugh artisan vegan vaporware hexagon. Polaroid fixie post-ironic venmo wolf ramps kale chips.
There should be no margin above this first sentence.
Blockquotes should be a lighter gray with a border along the left side in the secondary color.
There should be no margin below this final sentence.
This is a normal paragraph following a header. Knausgaard kale chips snackwave microdosing cronut copper mug swag synth bitters letterpress glossier craft beer. Mumblecore bushwick authentic gochujang vegan chambray meditation jean shorts irony. Viral farm-to-table kale chips, pork belly palo santo distillery activated charcoal aesthetic jianbing air plant woke lomo VHS organic. Tattooed locavore succulents heirloom, small batch sriracha echo park DIY af. Shaman you probably haven’t heard of them copper mug, crucifix green juice vape single-origin coffee brunch actually. Mustache etsy vexillologist raclette authentic fam. Tousled beard humblebrag asymmetrical. I love turkey, I love my job, I love my friends, I love Chardonnay!
Deae legum paulatimque terra, non vos mutata tacet: dic. Vocant docuique me plumas fila quin afuerunt copia haec o neque.
On big screens, paragraphs and headings should not take up the full container width, but we want tables, code blocks and similar to take the full width.
Scenester tumeric pickled, authentic crucifix post-ironic fam freegan VHS pork belly 8-bit yuccie PBR&B. I love this life we live in.
This is a blockquote following a header. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.
This is a code block following a header.
Next level leggings before they sold out, PBR&B church-key shaman echo park. Kale chips occupy godard whatever pop-up freegan pork belly selfies. Gastropub Belinda subway tile woke post-ironic seitan. Shabby chic man bun semiotics vape, chia messenger bag plaid cardigan.
- This is an unordered list following a header.
- This is an unordered list following a header.
- This is an unordered list following a header.
- This is an ordered list following a header.
- This is an ordered list following a header.
- This is an ordered list following a header.
What | Follows |
---|
A table | A header |
A table | A header |
A table | A header |
There’s a horizontal rule above and below this.
Here is an unordered list:
- Liverpool F.C.
- Chelsea F.C.
- Manchester United F.C.
And an ordered list:
- Michael Brecker
- Seamus Blake
- Branford Marsalis
And an unordered task list:
And a “mixed” task list:
And a nested list:
Jackson 5
- Michael
- Tito
- Jackie
- Marlon
- Jermaine
TMNT
- Leonardo
- Michelangelo
- Donatello
- Raphael
Definition lists can be used with Markdown syntax. Definition headers are bold.
- Name
- Godzilla
- Born
- 1952
- Birthplace
- Japan
- Color
- Green
Tables should have bold headings and alternating shaded rows.
Artist | Album | Year |
---|
Michael Jackson | Thriller | 1982 |
Prince | Purple Rain | 1984 |
Beastie Boys | License to Ill | 1986 |
If a table is too wide, it should scroll horizontally.
Artist | Album | Year | Label | Awards | Songs |
---|
Michael Jackson | Thriller | 1982 | Epic Records | Grammy Award for Album of the Year, American Music Award for Favorite Pop/Rock Album, American Music Award for Favorite Soul/R&B Album, Brit Award for Best Selling Album, Grammy Award for Best Engineered Album, Non-Classical | Wanna Be Startin' Somethin', Baby Be Mine, The Girl Is Mine, Thriller, Beat It, Billie Jean, Human Nature, P.Y.T. (Pretty Young Thing), The Lady in My Life |
Prince | Purple Rain | 1984 | Warner Brothers Records | Grammy Award for Best Score Soundtrack for Visual Media, American Music Award for Favorite Pop/Rock Album, American Music Award for Favorite Soul/R&B Album, Brit Award for Best Soundtrack/Cast Recording, Grammy Award for Best Rock Performance by a Duo or Group with Vocal | Let’s Go Crazy, Take Me With U, The Beautiful Ones, Computer Blue, Darling Nikki, When Doves Cry, I Would Die 4 U, Baby I’m a Star, Purple Rain |
Beastie Boys | License to Ill | 1986 | Mercury Records | noawardsbutthistablecelliswide | Rhymin & Stealin, The New Style, She’s Crafty, Posse in Effect, Slow Ride, Girls, (You Gotta) Fight for Your Right, No Sleep Till Brooklyn, Paul Revere, Hold It Now, Hit It, Brass Monkey, Slow and Low, Time to Get Ill |
Code snippets like var foo = "bar";
can be shown inline.
Also, this should vertically align
with this
and this.
Code can also be shown in a block element.
foo := "bar";
bar := "foo";
Code can also use syntax highlighting.
func main() {
input := `var foo = "bar";`
lexer := lexers.Get("javascript")
iterator, _ := lexer.Tokenise(nil, input)
style := styles.Get("github")
formatter := html.New(html.WithLineNumbers())
var buff bytes.Buffer
formatter.Format(&buff, style, iterator)
fmt.Println(buff.String())
}
Long, single-line code blocks should not wrap. They should horizontally scroll if they are too long. This line should be long enough to demonstrate this.
Inline code inside table cells should still be distinguishable.
Language | Code |
---|
Javascript | var foo = "bar"; |
Ruby | foo = "bar"{ |
Small images should be shown at their actual size.
Large images should always scale down and fit in the content container.
The photo above of the Spruce Picea abies shoot with foliage buds: Bjørn Erik Pedersen, CC-BY-SA.
Components
Alerts
This is an alert.
Note
This is an alert with a title.Note
This is an alert with a title and Markdown.This is a successful alert.
This is a warning.
Warning
This is a warning with a title.Another Heading
Add some sections here to see how the ToC looks like. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.
This Document
Inguina genus: Anaphen post: lingua violente voce suae meus aetate diversi. Orbis unam nec flammaeque status deam Silenum erat et a ferrea. Excitus rigidum ait: vestro et Herculis convicia: nitidae deseruit coniuge Proteaque adiciam eripitur? Sitim noceat signa probat quidem. Sua longis fugatis quidem genae.
Pixel Count
Tilde photo booth wayfarers cliche lomo intelligentsia man braid kombucha vaporware farm-to-table mixtape portland. PBR&B pickled cornhole ugh try-hard ethical subway tile. Fixie paleo intelligentsia pabst. Ennui waistcoat vinyl gochujang. Poutine salvia authentic affogato, chambray lumbersexual shabby chic.
Plaid hell of cred microdosing, succulents tilde pour-over. Offal shabby chic 3 wolf moon blue bottle raw denim normcore poutine pork belly.
External Links
Stumptown PBR&B keytar plaid street art, forage XOXO pitchfork selvage affogato green juice listicle pickled everyday carry hashtag. Organic sustainable letterpress sartorial scenester intelligentsia swag bushwick. Put a bird on it stumptown neutra locavore. IPhone typewriter messenger bag narwhal. Ennui cold-pressed seitan flannel keytar, single-origin coffee adaptogen occupy yuccie williamsburg chillwave shoreditch forage waistcoat.
This is the final element on the page and there should be no margin below this.
3 - Applicaties en software
Een overzicht van applicaties, containers en software (databases, grafieken, monitoring etc.)
This is a placeholder page that shows you how to use this template site.
4 - Config DB
Show your user how to work through some end to end examples.
This is a placeholder page that shows you how to use this template site.
Configuratie DB
Oke niet echt een Database maar een verzameling configuraties voor diverse systemen en technieken
Hier vind je bijvoorbeeld verschillende configuraties voor Shelly’s met ESPHome Firmware, of Automations van HA etc
Maar ook eventueel Docker (Compose) files
4.1 - ESPHome
ESPHome Configs.
This is a placeholder page that shows you how to use this template site.
ESPHome
Kort stukje text over ESPhome
4.1.1 - Shelly Configuraties
Place holder voor de shelly 1 configs
This is a typical blog post that includes images.
The front matter specifies the date of the blog post, its title, a short description that will be displayed on the blog landing page, and its author.
Including images
Here’s an image that includes a byline and a caption.
at the size and byline specified in the front matter.
4.1.2 - Shelly Configuraties
Place holder voor de shelly 25 configs
This is a typical blog post that includes images.
The front matter specifies the date of the blog post, its title, a short description that will be displayed on the blog landing page, and its author.
Including images
Here’s an image that includes a byline and a caption.
at the size and byline specified in the front matter.
5 - Contribution Guidelines
How to contribute to the docs
These basic sample guidelines assume that your Docsy site is deployed using Netlify and your files are stored in GitHub. You can use the guidelines “as is” or adapt them with your own instructions: for example, other deployment options, information about your doc project’s file structure, project-specific review guidelines, versioning guidelines, or any other information your users might find useful when updating your site. Kubeflow has a great example.
Don’t forget to link to your own doc repo rather than our example site! Also make sure users can find these guidelines from your doc repo README: either add them there and link to them from this page, add them here and link to them from the README, or include them in both locations.
We use Hugo to format and generate our website, the
Docsy theme for styling and site structure,
and Netlify to manage the deployment of the site.
Hugo is an open-source static site generator that provides us with templates,
content organisation in a standard directory structure, and a website generation
engine. You write the pages in Markdown (or HTML if you want), and Hugo wraps them up into a website.
All submissions, including submissions by project members, require review. We
use GitHub pull requests for this purpose. Consult
GitHub Help for more
information on using pull requests.
Quick start with Netlify
Here’s a quick guide to updating the docs. It assumes you’re familiar with the
GitHub workflow and you’re happy to use the automated preview of your doc
updates:
- Fork the Goldydocs repo on GitHub.
- Make your changes and send a pull request (PR).
- If you’re not yet ready for a review, add “WIP” to the PR name to indicate
it’s a work in progress. (Don’t add the Hugo property
“draft = true” to the page front matter, because that prevents the
auto-deployment of the content preview described in the next point.)
- Wait for the automated PR workflow to do some checks. When it’s ready,
you should see a comment like this: deploy/netlify — Deploy preview ready!
- Click Details to the right of “Deploy preview ready” to see a preview
of your updates.
- Continue updating your doc and pushing your changes until you’re happy with
the content.
- When you’re ready for a review, add a comment to the PR, and remove any
“WIP” markers.
Updating a single page
If you’ve just spotted something you’d like to change while using the docs, Docsy has a shortcut for you:
- Click Edit this page in the top right hand corner of the page.
- If you don’t already have an up to date fork of the project repo, you are prompted to get one - click Fork this repository and propose changes or Update your Fork to get an up to date version of the project to edit. The appropriate page in your fork is displayed in edit mode.
- Follow the rest of the Quick start with Netlify process above to make, preview, and propose your changes.
Previewing your changes locally
If you want to run your own local Hugo server to preview your changes as you work:
- Follow the instructions in Getting started to install Hugo and any other tools you need. You’ll need at least Hugo version 0.45 (we recommend using the most recent available version), and it must be the extended version, which supports SCSS.
- Fork the Goldydocs repo repo into your own project, then create a local copy using
git clone
. Don’t forget to use --recurse-submodules
or you won’t pull down some of the code you need to generate a working site.
git clone --recurse-submodules --depth 1 https://github.com/google/docsy-example.git
- Run
hugo server
in the site root directory. By default your site will be available at http://localhost:1313/. Now that you’re serving your site locally, Hugo will watch for changes to the content and automatically refresh your site. - Continue with the usual GitHub workflow to edit files, commit them, push the
changes up to your fork, and create a pull request.
Creating an issue
If you’ve found a problem in the docs, but you’re not sure how to fix it yourself, please create an issue in the Goldydocs repo. You can also create an issue about a specific page by clicking the Create Issue button in the top right hand corner of the page.
Useful resources
6 - Examples
See your project in action!
This is a placeholder page that shows you how to use this template site.
Do you have any example applications or code for your users in your repo or elsewhere? Link to your examples here.
6.1 - Reference
Low level reference docs for your project.
This is a placeholder page that shows you how to use this template site.
If your project has an API, configuration, or other reference - anything that users need to look up that’s at an even lower level than a single task - put (or link to it) here. You can serve and link to generated reference docs created using Doxygen,
Javadoc, or other doc generation tools by putting them in your static/
directory. Find out more in Adding static content. For OpenAPI reference, Docsy also provides a Swagger UI layout and shortcode that renders Swagger UI using any OpenAPI YAML or JSON file as source.
6.1.1 - Parameter Reference
A short lead description about this content page. It can be bold or italic and can be split over multiple paragraphs.
This is a placeholder page. Replace it with your own content.
Text can be bold, italic, or strikethrough. Links should be blue with no underlines (unless hovered over).
There should be whitespace between paragraphs. Vape migas chillwave sriracha poutine try-hard distillery. Tattooed shabby chic small batch, pabst art party heirloom letterpress air plant pop-up. Sustainable chia skateboard art party banjo cardigan normcore affogato vexillologist quinoa meggings man bun master cleanse shoreditch readymade. Yuccie prism four dollar toast tbh cardigan iPhone, tumblr listicle live-edge VHS. Pug lyft normcore hot chicken biodiesel, actually keffiyeh thundercats photo booth pour-over twee fam food truck microdosing banh mi. Vice activated charcoal raclette unicorn live-edge post-ironic. Heirloom vexillologist coloring book, beard deep v letterpress echo park humblebrag tilde.
90’s four loko seitan photo booth gochujang freegan tumeric listicle fam ugh humblebrag. Bespoke leggings gastropub, biodiesel brunch pug fashion axe meh swag art party neutra deep v chia. Enamel pin fanny pack knausgaard tofu, artisan cronut hammock meditation occupy master cleanse chartreuse lumbersexual. Kombucha kogi viral truffaut synth distillery single-origin coffee ugh slow-carb marfa selfies. Pitchfork schlitz semiotics fanny pack, ugh artisan vegan vaporware hexagon. Polaroid fixie post-ironic venmo wolf ramps kale chips.
There should be no margin above this first sentence.
Blockquotes should be a lighter gray with a border along the left side in the secondary color.
There should be no margin below this final sentence.
This is a normal paragraph following a header. Knausgaard kale chips snackwave microdosing cronut copper mug swag synth bitters letterpress glossier craft beer. Mumblecore bushwick authentic gochujang vegan chambray meditation jean shorts irony. Viral farm-to-table kale chips, pork belly palo santo distillery activated charcoal aesthetic jianbing air plant woke lomo VHS organic. Tattooed locavore succulents heirloom, small batch sriracha echo park DIY af. Shaman you probably haven’t heard of them copper mug, crucifix green juice vape single-origin coffee brunch actually. Mustache etsy vexillologist raclette authentic fam. Tousled beard humblebrag asymmetrical. I love turkey, I love my job, I love my friends, I love Chardonnay!
Deae legum paulatimque terra, non vos mutata tacet: dic. Vocant docuique me plumas fila quin afuerunt copia haec o neque.
On big screens, paragraphs and headings should not take up the full container width, but we want tables, code blocks and similar to take the full width.
Scenester tumeric pickled, authentic crucifix post-ironic fam freegan VHS pork belly 8-bit yuccie PBR&B. I love this life we live in.
This is a blockquote following a header. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.
This is a code block following a header.
Next level leggings before they sold out, PBR&B church-key shaman echo park. Kale chips occupy godard whatever pop-up freegan pork belly selfies. Gastropub Belinda subway tile woke post-ironic seitan. Shabby chic man bun semiotics vape, chia messenger bag plaid cardigan.
- This is an unordered list following a header.
- This is an unordered list following a header.
- This is an unordered list following a header.
- This is an ordered list following a header.
- This is an ordered list following a header.
- This is an ordered list following a header.
What | Follows |
---|
A table | A header |
A table | A header |
A table | A header |
There’s a horizontal rule above and below this.
Here is an unordered list:
- Liverpool F.C.
- Chelsea F.C.
- Manchester United F.C.
And an ordered list:
- Michael Brecker
- Seamus Blake
- Branford Marsalis
And an unordered task list:
And a “mixed” task list:
And a nested list:
Jackson 5
- Michael
- Tito
- Jackie
- Marlon
- Jermaine
TMNT
- Leonardo
- Michelangelo
- Donatello
- Raphael
Definition lists can be used with Markdown syntax. Definition headers are bold.
- Name
- Godzilla
- Born
- 1952
- Birthplace
- Japan
- Color
- Green
Tables should have bold headings and alternating shaded rows.
Artist | Album | Year |
---|
Michael Jackson | Thriller | 1982 |
Prince | Purple Rain | 1984 |
Beastie Boys | License to Ill | 1986 |
If a table is too wide, it should scroll horizontally.
Artist | Album | Year | Label | Awards | Songs |
---|
Michael Jackson | Thriller | 1982 | Epic Records | Grammy Award for Album of the Year, American Music Award for Favorite Pop/Rock Album, American Music Award for Favorite Soul/R&B Album, Brit Award for Best Selling Album, Grammy Award for Best Engineered Album, Non-Classical | Wanna Be Startin' Somethin', Baby Be Mine, The Girl Is Mine, Thriller, Beat It, Billie Jean, Human Nature, P.Y.T. (Pretty Young Thing), The Lady in My Life |
Prince | Purple Rain | 1984 | Warner Brothers Records | Grammy Award for Best Score Soundtrack for Visual Media, American Music Award for Favorite Pop/Rock Album, American Music Award for Favorite Soul/R&B Album, Brit Award for Best Soundtrack/Cast Recording, Grammy Award for Best Rock Performance by a Duo or Group with Vocal | Let’s Go Crazy, Take Me With U, The Beautiful Ones, Computer Blue, Darling Nikki, When Doves Cry, I Would Die 4 U, Baby I’m a Star, Purple Rain |
Beastie Boys | License to Ill | 1986 | Mercury Records | noawardsbutthistablecelliswide | Rhymin & Stealin, The New Style, She’s Crafty, Posse in Effect, Slow Ride, Girls, (You Gotta) Fight for Your Right, No Sleep Till Brooklyn, Paul Revere, Hold It Now, Hit It, Brass Monkey, Slow and Low, Time to Get Ill |
Code snippets like var foo = "bar";
can be shown inline.
Also, this should vertically align
with this
and this.
Code can also be shown in a block element.
foo := "bar";
bar := "foo";
Code can also use syntax highlighting.
func main() {
input := `var foo = "bar";`
lexer := lexers.Get("javascript")
iterator, _ := lexer.Tokenise(nil, input)
style := styles.Get("github")
formatter := html.New(html.WithLineNumbers())
var buff bytes.Buffer
formatter.Format(&buff, style, iterator)
fmt.Println(buff.String())
}
Long, single-line code blocks should not wrap. They should horizontally scroll if they are too long. This line should be long enough to demonstrate this.
Inline code inside table cells should still be distinguishable.
Language | Code |
---|
Javascript | var foo = "bar"; |
Ruby | foo = "bar"{ |
Small images should be shown at their actual size.
Large images should always scale down and fit in the content container.
The photo above of the Spruce Picea abies shoot with foliage buds: Bjørn Erik Pedersen, CC-BY-SA.
Components
Alerts
This is an alert.
Note
This is an alert with a title.Note
This is an alert with a title and Markdown.This is a successful alert.
This is a warning.
Warning
This is a warning with a title.Another Heading