diff --git a/doc/Makefile b/doc/Makefile
index f8bc9547..9cadbdba 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -12,6 +12,8 @@ DOCS=\
 
 hardware.adoc: hardware.nix
 	pandoc -f rst -t asciidoc -o $@ hardware.rst
+	# don't even ask
+	sed -E -i.bak -e 's/^=(=*) /\1 /g' hardware.adoc
 
 html: Makefile  $(patsubst %,%.adoc,$(DOCS))
 	asciidoctor  -D _build -d book index.adoc
diff --git a/doc/admin.adoc b/doc/admin.adoc
index 97b47056..681dc003 100644
--- a/doc/admin.adoc
+++ b/doc/admin.adoc
@@ -4,7 +4,7 @@
 
 Liminix services are built on s6-rc, which is itself layered on s6.
 Services are defined at build time in your configuration (see
-`+configuration-services+` for information) and can't be added
+<<_services>> for information) and can't be added
 to/changed at runtime, but to monitor events or diagnose problems you
 may need to inspect them on the running system. Here are some of the
 most commonly used s6,-rc commands:
diff --git a/doc/installation.adoc b/doc/installation.adoc
index 8a194e5b..dc40f416 100644
--- a/doc/installation.adoc
+++ b/doc/installation.adoc
@@ -25,7 +25,7 @@ deploy onto, sometimes due to differences in the uses these devices are
 put to.
 
 For a more full description of how to configure Liminix, see
-`+configuration+`. Assuming for the moment that you want a typical home
+<<_configuration>>. Assuming for the moment that you want a typical home
 wireless gateway/router, the best way to get started is to copy
 `+examples/rotuer.nix+` and edit it for your requirements.
 
diff --git a/doc/tutorial.adoc b/doc/tutorial.adoc
index 37d21ec3..2b96e811 100644
--- a/doc/tutorial.adoc
+++ b/doc/tutorial.adoc
@@ -138,10 +138,10 @@ device also _ought_ to work here, but you accept the slightly greater
 bricking risk if it doesn't.
 ====
 
-See `+hardware+` for device support status.
+See <<_supported_hardware>> for device support status.
 
-You may want to read and inwardly digest the Develoment Manual section
-`+serial+` when you start working with Liminix on real hardware. You
+You may want to read and inwardly digest the section about <<serial>>
+connections when you start working with Liminix on real hardware. You
 won't _need_ serial access for this example, assuming it works, but it
 allows you to see the boot monitor and kernel messages, and to login
 directly to the device if for some reason it doesn't bring its network