diff --git a/doc/meson.build b/doc/meson.build
index a4fc17150..4b1c4728a 100644
--- a/doc/meson.build
+++ b/doc/meson.build
@@ -1,12 +1,12 @@
 if pandoc.found()
     custom_target(
-        input: ['manpage-header.md', 'structure-id.md', 'netplan-yaml.md', 'manpage-footer.md'],
+        input: ['manpage-header.md', 'explanation/structure-id.md', 'reference/netplan-yaml.md', 'manpage-footer.md'],
         output: 'netplan.5',
         command: [pandoc, '-s', '-o', '@OUTPUT@', '--from=markdown-smart', '@INPUT@'],
         install: true,
         install_dir: join_paths(get_option('mandir'), 'man5'))
     custom_target(
-        input: 'netplan-yaml.md',
+        input: 'reference/netplan-yaml.md',
         output: 'netplan.html',
         command: [pandoc, '-s', '--metadata', 'title="Netplan reference"', '--toc', '-o', '@OUTPUT@', '@INPUT@'],
         install: true,
@@ -15,7 +15,7 @@ if pandoc.found()
       'netplan-apply', 'netplan-dbus', 'netplan-generate', 'netplan-get', 'netplan-set',
       'netplan-try', 'netplan-info', 'netplan-ip', 'netplan-status', 'netplan-rebind',
       ]
-        markdown = files(doc + '.md')
+        markdown = files('reference/' + doc + '.md')
         manpage = doc + '.8'
         custom_target(
             input: markdown,
diff --git a/tests/validate_docs.sh b/tests/validate_docs.sh
index 354dd5fe5..1fe478f69 100755
--- a/tests/validate_docs.sh
+++ b/tests/validate_docs.sh
@@ -17,12 +17,12 @@ fi
 for term in $(sed -n 's/[ ]\+{"\([a-z0-9-]\+\)", YAML_[A-Z]\+_NODE.*/\1/p' src/parse.c | sort | uniq); do
     # it can be documented in the following ways.
     # 1. "Properties for device type `blah:`
-    if egrep "## Properties for device type \`$term:\`" doc/netplan-yaml.md > /dev/null; then
+    if egrep "## Properties for device type \`$term:\`" doc/reference/netplan-yaml.md > /dev/null; then
         continue
     fi
 
     # 2. "[blah, ]**blah**[, **blah2**]: (scalar|bool|...)
-    if egrep "Alias: \*\*\`$term\`\*\*|\*\*\`$term\`\*\*.*\((scalar|boolean|mapping|sequence of scalars|sequence of mappings|sequence of sequence of scalars)" doc/netplan-yaml.md > /dev/null; then
+    if egrep "Alias: \*\*\`$term\`\*\*|\*\*\`$term\`\*\*.*\((scalar|boolean|mapping|sequence of scalars|sequence of mappings|sequence of sequence of scalars)" doc/reference/netplan-yaml.md > /dev/null; then
         continue
     fi