Merge pull request #561 from ukkopahis/doc-attr-anchors

Docs: Refactor to define anchors using attribute list

Author: Slyke

docs/Containers/AdGuardHome.md

@@ -9,7 +9,7 @@
 
 AdGuard Home and PiHole perform similar functions. They use the same ports so you can **not** run both at the same time. You must choose one or the other.
 
-## <a name="quickStart"></a>Quick Start
+## Quick Start { #quickStart }
 
 When you first install AdGuard Home:
 

docs/Containers/Blynk_server.md

@@ -2,7 +2,7 @@
 
 This document discusses an IOTstack-specific version of Blynk-Server. It is built on top of an [Ubuntu](https://hub.docker.com/_/ubuntu) base image using a *Dockerfile*.
 
-## <a name="references"></a>References
+## References { #references }
 
 - [Ubuntu base image](https://hub.docker.com/_/ubuntu) at DockerHub
 - [Peter Knight Blynk-Server fork](https://github.com/Peterkn2001/blynk-server) at GitHub (includes documentation)
@@ -18,7 +18,7 @@ Acknowledgement:
 
 - Original writeup from @877dev
 
-## <a name="significantFiles"></a>Significant directories and files
+## Significant directories and files { #significantFiles }
 
 ```
 ~/IOTstack
@@ -56,19 +56,19 @@ Everything in ❽:
 * will be replaced if it is not present when the container starts; but
 * will never be overwritten if altered by you.
 
-## <a name="howBlynkServerIOTstackGetsBuilt"></a>How Blynk Server gets built for IOTstack
+## How Blynk Server gets built for IOTstack { #howBlynkServerIOTstackGetsBuilt }
 
-### <a name="dockerHubImages"></a>GitHub Updates 
+### GitHub Updates  { #dockerHubImages }
 
 Periodically, the source code is updated and a new version is released. You can check for the latest version at the [releases page](https://github.com/Peterkn2001/blynk-server/releases/).
 
-### <a name="iotstackMenu"></a>IOTstack menu
+### IOTstack menu { #iotstackMenu }
 
 When you select Blynk Server in the IOTstack menu, the *template service definition* is copied into the *Compose* file.
 
 > Under old menu, it is also copied to the *working service definition* and then not really used.
 
-### <a name="iotstackFirstRun"></a>IOTstack first run 
+### IOTstack first run  { #iotstackFirstRun }
 
 On a first install of IOTstack, you run the menu, choose your containers, and are told to do this:
 
@@ -131,15 +131,15 @@ You *may* see the same pattern in *Portainer*, which reports the ***base image**
 
 > Whether you see one or two rows depends on the version of `docker-compose` you are using and how your version of `docker-compose` builds local images.
 
-## <a name="logging"></a>Logging
+## Logging { #logging }
 
 You can inspect Blynk Server's log by:
 
 ```console
 $ docker logs blynk_server
 ```
 
-## <a name="editConfiguration"></a>Changing Blynk Server's configuration
+## Changing Blynk Server's configuration { #editConfiguration }
 
 The first time you launch the `blynk_server` container, the following structure will be created in the persistent storage area:
 
@@ -158,7 +158,7 @@ $ cd ~/IOTstack
 $ docker-compose restart blynk_server
 ```
 
-## <a name="cleanSlate"></a>Getting a clean slate
+## Getting a clean slate { #cleanSlate }
 
 Erasing Blynk Server's persistent storage area triggers self-healing and restores known defaults:
 
@@ -178,7 +178,7 @@ Note:
 	$ docker-compose restart blynk_server
 	```
 
-## <a name="upgradingBlynkServer"></a>Upgrading Blynk Server
+## Upgrading Blynk Server { #upgradingBlynkServer }
 
 To find out when a new version has been released, you need to visit the [Blynk-Server releases](https://github.com/Peterkn2001/blynk-server/releases/) page at GitHub.
 
@@ -220,11 +220,11 @@ At the time of writing, version 0.41.16 was the most up-to-date. Suppose that ve
 
 		The second `prune` will only be needed if there is an old *base image* and that, in turn, depends on the version of `docker-compose` you are using and how your version of `docker-compose` builds local images.
 
-## <a name="usingBlynkServer"></a>Using Blynk Server
+## Using Blynk Server { #usingBlynkServer }
 
 See the [References](#references) for documentation links.
 
-### <a name="blynkAdmin"></a>Connecting to the administrative UI
+### Connecting to the administrative UI { #blynkAdmin }
 
 To connect to the administrative interface, navigate to:
 
@@ -237,7 +237,7 @@ You may encounter browser security warnings which you will have to acknowledge i
 - username = `[email protected]`
 - password = `admin`
 
-### <a name="changePassword"></a>Change username and password
+### Change username and password { #changePassword }
 
 1. Click on Users > "email address" and edit email, name and password. 
 2. Save changes.
@@ -248,19 +248,19 @@ You may encounter browser security warnings which you will have to acknowledge i
 	$ docker-compose restart blynk_server
 	```
 
-### <a name="gmailSetup"></a>Setup gmail
+### Setup gmail { #gmailSetup }
 
 Optional step, useful for getting the auth token emailed to you.
 (To be added once confirmed working....)
 
-### <a name="mobileSetup"></a>iOS/Android app setup
+### iOS/Android app setup { #mobileSetup }
 
 1. When setting up the application on your mobile be sure to select "custom" setup [see](https://github.com/Peterkn2001/blynk-server#app-and-sketch-changes).
 2. Press "New Project"
 3. Give it a name, choose device "Raspberry Pi 3 B" so you have plenty of [virtual pins](http://help.blynk.cc/en/articles/512061-what-is-virtual-pins) available, and lastly select WiFi.
 4. Create project and the [auth token](https://docs.blynk.cc/#getting-started-getting-started-with-the-blynk-app-4-auth-token) will be emailed to you (if emails configured). You can also find the token in app under the phone app settings, or in the admin web interface by clicking Users>"email address" and scroll down to token.
 
-### <a name="quickAppGuide"></a>Quick usage guide for app
+### Quick usage guide for app { #quickAppGuide }
 
 1. Press on the empty page, the widgets will appear from the right.
 2. Select your widget, let's say a button.
@@ -273,7 +273,7 @@ Optional step, useful for getting the auth token emailed to you.
 
 Enter Node-Red.....
 
-### <a name="enterNodeRed"></a>Node-RED
+### Node-RED { #enterNodeRed }
 
 1. Install `node-red-contrib-blynk-ws` from Manage Palette.
 2. Drag a "write event" node into your flow, and connect to a debug node

docs/Containers/Home-Assistant.md

@@ -2,7 +2,7 @@
 
 Home Assistant is a home automation platform. It is able to track and control all devices at your home and offer a platform for automating control.
 
-## <a name="references"></a>References
+## References { #references }
 
 - [Home Assistant home page](https://www.home-assistant.io/)
 
@@ -13,7 +13,7 @@ Home Assistant is a home automation platform. It is able to track and control al
 - [DockerHub](https://hub.docker.com/r/homeassistant/home-assistant/)
 
 
-## <a name="twoVersions"></a>Home Assistant: two versions
+## Home Assistant: two versions { #twoVersions }
 
 There are two versions of Home Assistant:
 
@@ -36,7 +36,7 @@ If Home Assistant Container will not do what you want then, basically, you will
 * One running Raspberry Pi OS ("Raspbian") hosting IOTstack; and
 * Another dedicated to running [Home Assistant Operating System](https://www.home-assistant.io/installation/raspberrypi).
 
-## <a name="installHAContainer"></a>Installing Home Assistant Container
+## Installing Home Assistant Container { #installHAContainer }
 
 Home Assistant (Container) can be found in the `Build Stack` menu. Selecting it in this menu results in a service definition being added to:
 
@@ -61,7 +61,7 @@ $ cd ~/IOTstack
 $ docker-compose up -d
 ```
 
-## <a name="usingBluetooth"></a>Using bluetooth from the container
+## Using bluetooth from the container { #usingBluetooth }
 
 In order to be able to use BT & BLE devices from HA integrations, make sure that Bluetooth is enabled:
 
@@ -98,7 +98,7 @@ If `AutoEnable` is either missing or not set to `true`, then:
 
 See also: [Scribles: Auto Power On Bluetooth Adapter on Boot-up](https://scribles.net/auto-power-on-bluetooth-adapter-on-boot-up/).
 
-## <a name="httpsWithSSLcert"></a>HTTPS with a valid SSL certificate
+## HTTPS with a valid SSL certificate { #httpsWithSSLcert }
 
 Some HA integrations (e.g google assistant) require your HA API to be
 accessible via https with a valid certificate. You can configure HA to do this:
@@ -227,7 +227,7 @@ your RPi hostname is raspberrypi)
     `https://homeassistant.<yourdomain>.duckdns.org/` Now the certificate
     should work without any warnings.
 
-## <a name="hassioBackground"></a>about Supervised Home Assistant
+## about Supervised Home Assistant { #hassioBackground }
 
 IOTstack used to offer a menu entry leading to a convenience script that could install Supervised Home Assistant. That script stopped working when Home Assistant changed their approach. The script's author [made it clear](https://github.com/Kanga-Who/home-assistant/blob/master/Supervised%20on%20Raspberry%20Pi%20with%20Debian.md) that script's future was bleak so the affordance was [removed from IOTstack](https://github.com/SensorsIot/IOTstack/pull/493).
 

docs/Containers/MariaDB.md

@@ -68,9 +68,9 @@ To close the terminal session, either:
 * type "exit" and press <kbd>return</kbd>; or
 * press <kbd>control</kbd>+<kbd>d</kbd>.
 
-## <a name="healthCheck"></a>Container health check
+## Container health check { #healthCheck }
 
-### <a name="healthCheckTheory"></a>theory of operation
+### theory of operation { #healthCheckTheory }
 
 A script , or "agent", to assess the health of the MariaDB container has been added to the *local image* via the *Dockerfile*. In other words, the script is specific to IOTstack.
 
@@ -92,7 +92,7 @@ The agent is invoked 30 seconds after the container starts, and every 30 seconds
 
 4. If all of those steps succeed, the agent concludes that MariaDB is functioning properly and returns "healthy".
 
-### <a name="healthCheckMonitor"></a>monitoring health-check
+### monitoring health-check { #healthCheckMonitor }
 
 Portainer's *Containers* display contains a *Status* column which shows health-check results for all containers that support the feature.
 
@@ -125,7 +125,7 @@ Possible reply patterns are:
 	mariadb   Up About a minute (unhealthy)
 	```
 
-### <a name="healthCheckCustom"></a>customising health-check
+### customising health-check { #healthCheckCustom }
 
 You can customise the operation of the health-check agent by editing the `mariadb` service definition in your *Compose* file:
 

docs/Containers/Mosquitto.md

@@ -159,7 +159,7 @@ You *may* see the same pattern in Portainer, which reports the *base image* as "
 
 > Whether you see one or two rows depends on the version of `docker-compose` you are using and how your version of `docker-compose` builds local images.
 
-### <a name="migration"></a>Migration considerations
+### Migration considerations { #migration }
 
 Under the original IOTstack implementation of Mosquitto (just "as it comes" from *DockerHub*), the service definition expected the configuration files to be at:
 
@@ -518,7 +518,7 @@ The agent is invoked 30 seconds after the container starts, and every 30 seconds
 * Subscribes to the same broker for the same topic for a single message event.
 * Compares the payload sent with the payload received. If the payloads (ie time-stamps) match, the agent concludes that the Mosquitto broker (the process running inside the same container) is functioning properly for round-trip messaging.
 
-### <a name="healthCheckMonitor"></a>monitoring health-check
+### monitoring health-check { #healthCheckMonitor }
 
 Portainer's *Containers* display contains a *Status* column which shows health-check results for all containers that support the feature.
 
@@ -564,7 +564,7 @@ Notes:
 * If you enable authentication for your Mosquitto broker, you will need to add `-u «user»` and `-P «password»` parameters to this command.
 * You should expect to see a new message appear approximately every 30 seconds. That indicates the health-check agent is functioning normally. Use <kbd>control</kbd>+<kbd>c</kbd> to terminate the command.
 
-### <a name="healthCheckCustom"></a>customising health-check
+### customising health-check { #healthCheckCustom }
 
 You can customise the operation of the health-check agent by editing the `mosquitto` service definition in your *Compose* file:
 
@@ -655,7 +655,7 @@ Your existing Mosquitto container continues to run while the rebuild proceeds. O
 
 The `prune` is the simplest way of cleaning up. The first call removes the old *local image*. The second call cleans up the old *base image*. Whether an old *base image* exists depends on the version of `docker-compose` you are using and how your version of `docker-compose` builds local images.
 
-### <a name="versionPinning"></a>Mosquitto version pinning
+### Mosquitto version pinning { #versionPinning }
 
 If an update to Mosquitto introduces a breaking change, you can revert to an earlier know-good version by pinning to that version. Here's how:
 

docs/Containers/NextCloud.md

@@ -1,6 +1,6 @@
 # Nextcloud
 
-## <a name="serviceDefinition"></a>Service definition
+## Service definition { #serviceDefinition }
 
 This is the **core** of the IOTstack Nextcloud service definition:
 
@@ -54,7 +54,7 @@ Under new-menu, the menu can generate random passwords for you. You can either u
 
 The passwords need to be set before you bring up the Nextcloud service for the first time but the following initialisation steps assume you might not have done that and always start over from a clean slate.
 
-## <a name="initialisation"></a>Initialising Nextcloud 
+## Initialising Nextcloud  { #initialisation }
 
 1. Be in the correct directory:
 
@@ -174,7 +174,7 @@ The passwords need to be set before you bring up the Nextcloud service for the f
 
 	![Dashboard](./images/nextcloud-dashboard.png)
 
-## <a name="untrustedDomain"></a>"Access through untrusted domain"
+## "Access through untrusted domain" { #untrustedDomain }
 
 During Nextcloud initialisation you had to choose between an IP address, a domain name or a host name. Now that Nextcloud is running, you have the opportunity to expand your connection options.
 
@@ -243,7 +243,7 @@ See also:
 
 * [Nextcloud documentation - trusted domains](https://docs.nextcloud.com/server/21/admin_manual/installation/installation_wizard.html#trusted-domains).
 
-### <a name="dnsAlias"></a>Using a DNS alias for your Nextcloud service
+### Using a DNS alias for your Nextcloud service { #dnsAlias }
 
 The examples above include using a DNS alias (a CNAME record) for your Nextcloud service. If you decide to do that, you may see this warning in the log:
 
@@ -257,17 +257,17 @@ You can silence the warning by editing the Nextcloud service definition in `dock
     hostname: nextcloud.mydomain.com
 ```
 
-## <a name="security"></a>Security considerations
+## Security considerations { #security }
 
 Nextcloud traffic is not encrypted. Do **not** expose it to the web by opening a port on your home router. Instead, use a VPN like Wireguard to provide secure access to your home network, and let your remote clients access Nextcloud over the VPN tunnel.
 
-## <a name="healthCheck"></a>Container health check 
+## Container health check  { #healthCheck }
 
 A script , or "agent", to assess the health of the MariaDB container has been added to the *local image* via the *Dockerfile*. In other words, the script is specific to IOTstack.
 
 Because it is an instance of MariaDB, Nextcloud_DB inherits the health-check agent. See the [IOTstack MariaDB](MariaDB.md) documentation for more information.
 
-## <a name="updatingNextcloud"></a>Keeping Nextcloud up-to-date
+## Keeping Nextcloud up-to-date { #updatingNextcloud }
 
 To update the `nextcloud` container:
 
@@ -290,7 +290,7 @@ $ docker system prune
 
 The first "prune" removes the old *local* image, the second removes the old *base* image. Whether an old *base image* exists depends on the version of `docker-compose` you are using and how your version of `docker-compose` builds local images.
 
-## <a name="backups"></a>Backups
+## Backups { #backups }
 
 Nextcloud is currently excluded from the IOTstack-supplied backup scripts due to its potential size.