Doc-rooted mounts and more

docsy.dev/.gitignore

@@ -3,3 +3,6 @@
 /public
 resources/
 tmp
+
+# Generated files
+/config/doc-rooted/module.yaml

docsy.dev/config/_default/hugo.yaml

@@ -177,10 +177,12 @@ module:
     - source: content/fr
       target: content
       sites: { matrix: { languages: [fr] } }
+      # files: ['! content/fr/_index.md'] # for doc-rooted: uncomment
     # English content for en and as fallback for fr (other pages)
     - source: content/en
       target: content
       sites: &sites { matrix: { languages: [en, fr] } }
+      # files: ['! content/en/_index.md'] # for doc-rooted: uncomment
     # Mount the repo root *.md files for both languages
     - source: ../AGENTS.md
       target: content/project/repo/AGENTS.md

docsy.dev/config/_default/params.yaml

@@ -7,7 +7,7 @@
 #   status: archived # Then fetch include
 
 version: &docsyVersion 0.14.3-dev
-tdBuildId: 010-over-main-1aae2c92
+tdBuildId: 011-over-main-09a5d40d
 versionLatest: &versionLatest v0.14.2
 version_menu: *docsyVersion
 version_menu_pagelinks: true

docsy.dev/content/en/docs/best-practices/_index.md

@@ -4,7 +4,6 @@ weight: 9
 description: >
   Optional guidance and recommendations about organizing, authoring, and
   managing your technical documentation.
-sidebar_root_for: children
 ---
 
 Use this section to learn about some of the best practices around creating

docsy.dev/content/en/docs/content/_index.md

@@ -2,5 +2,4 @@
 title: Content and Customization
 weight: 3
 description: How to add content to and customize your Docsy site.
-sidebar_root_for: self
 ---

docsy.dev/content/en/docs/content/navigation.md

@@ -482,13 +482,19 @@ sidebar_root_for: self
 ---
 ```
 
+{{< comment >}}
+
+FIXME: Add examples under test and refer to them here.
+
 Examples:
 
 | `sidebar_root_for` | Example                                     |
 | ------------------ | ------------------------------------------- |
 | `self`             | [Content and customization](/docs/content/) |
 | `children`         | [Best practices](/docs/best-practices/)     |
 
+{{< /comment >}}
+
 To navigate out of a rooted section, click the “up” icon in the sidebar next to
 the section title.
 

docsy.dev/content/en/docs/get-started/docsy-as-module/_index.md

@@ -4,7 +4,6 @@ weight: 1
 date: 2021-12-08T10:33:16+01:00
 description: >
   Learn how to get started with Docsy by using the theme as a Hugo Module.
-sidebar_root_for: children
 ---
 
 [Hugo modules](https://gohugo.io/hugo-modules/) are the simplest and latest way

docsy.dev/package.json

@@ -8,9 +8,11 @@
     "_check:links--warn": "npm run _check:links || (echo; echo 'WARNING: see link-checker output for issues.'; echo)",
     "_check:links": "make --keep-going check-links",
     "_commit:public": "HASH=$(git rev-parse --short main); cd public && git add -A && git commit --allow-empty -m \"Site at $HASH\"",
+    "_gen-config": "perl scripts/gen-doc-rooted-module.pl",
     "_hugo-dev-test": "npm run _hugo-dev -- --templateMetrics --templateMetricsHints",
     "_hugo-dev": "cross-env npm run _hugo -- -e \"${TD_BUILD_CTX:-dev}\" -DFE",
     "_hugo": "hugo --cleanDestinationDir --logLevel info --themesDir ../..",
+    "_prebuild": "npm run _gen-config",
     "_postbuild": "npm run _check:links--warn",
     "_serve": "npm run _hugo-dev -- serve --disableFastRender --renderToMemory",
     "build:preview": "cross-env npm run _hugo-dev -- --minify --baseURL \"${DEPLOY_PRIME_URL:-http://localhost}\"",
@@ -25,6 +27,9 @@
     "make:public": "git init -b main public",
     "postbuild:preview": "npm run _postbuild",
     "postbuild:production": "npm run _postbuild",
+    "prebuild": "npm run _prebuild",
+    "prebuild:preview": "npm run _prebuild",
+    "prebuild:production": "npm run _prebuild",
     "precheck:links:all": "npm run build",
     "precheck:links": "npm run build",
     "prepare-disabled": "cd .. && npm install",

docsy.dev/scripts/gen-doc-rooted-module.pl

@@ -0,0 +1,79 @@
+#!/usr/bin/env perl
+#
+# Generate config/doc-rooted/module.yaml from the mounts section in
+# config/_default/hugo.yaml. Commented lines with "# for doc-rooted: uncomment"
+# (case insensitive) are enabled (uncommented) in the output. Other commands
+# may be added later.
+#
+# Usage: perl scripts/gen-doc-rooted-module.pl
+# Run from the docsy.dev directory.
+
+use strict;
+use warnings;
+
+# Return lines from $lines starting at a line matching $marker (regex) until the
+# end of that section (next line at same or lesser indent) or end of array.
+sub get_section {
+    my ($lines, $marker) = @_;
+    my @out;
+    my $marker_indent = -1;
+
+    for my $line (@$lines) {
+        if ($marker_indent < 0) {
+            next unless $line =~ $marker;
+            $marker_indent = $line =~ m/^(\s*)/ ? length($1) : 0;
+            push @out, $line;
+            next;
+        }
+        my $indent = $line =~ m/^(\s*)/ ? length($1) : 0;
+        last if $line =~ m/\S/ && $indent <= $marker_indent;
+        push @out, $line;
+    }
+    return @out;
+}
+
+# Remove $n leading spaces from each line (only when the line has at least $n).
+sub unindent {
+    my ($lines, $n) = @_;
+    return map { /^\s{$n,}/ ? substr($_, $n) : $_ } @$lines;
+}
+
+# Apply "for doc-rooted: <command>" directives. For "uncomment", drop the leading
+# "# " and leave the directive in place. Other commands may be added later.
+sub apply_directives {
+    my ($lines) = @_;
+    my @out;
+    for my $line (@$lines) {
+        if ($line =~ m/^(\s*)#\s+(.+?)(\s+#\s*for\s+doc-rooted:\s*uncomment\s*)$/i) {
+            push @out, $1 . $2 . $3;
+        } else {
+            push @out, $line;
+        }
+    }
+    return @out;
+}
+
+my $config_default = 'config/_default/hugo.yaml';
+my $config_out     = 'config/doc-rooted/module.yaml';
+
+open my $in, '<', $config_default or die "Cannot read $config_default: $!";
+my @lines = <$in>;
+close $in;
+
+my @section = get_section(\@lines, qr/^\s*mounts:\s*$/);
+die "Could not find 'mounts:' section in $config_default\n" unless @section;
+
+@section = unindent(\@section, 2);
+@section = apply_directives(\@section);
+
+my $header = <<'HEADER';
+# DO NOT EDIT. Generated by scripts/gen-doc-rooted-module.pl from
+# config/_default/hugo.yaml (module.mounts).
+
+HEADER
+
+open my $out, '>', $config_out or die "Cannot write $config_out: $!";
+print $out $header, @section;
+close $out;
+
+print "Wrote $config_out\n";

package.json

@@ -1,6 +1,6 @@
 {
   "name": "docsy",
-  "version": "0.14.3-dev+010-over-main-1aae2c92",
+  "version": "0.14.3-dev+011-over-main-09a5d40d",
   "repository": "github:google/docsy",
   "homepage": "https://www.docsy.dev",
   "license": "Apache-2.0",
@@ -33,6 +33,7 @@
     "ci:prepare": "npm run docsy.dev-install && npm run _prepare && npm run _diff:check",
     "ci:test": "npm run ci:prepare && npm run check && npm run test:website && npm run ci:post",
     "docsy.dev-install": "npm run _cd:docsy.dev -- npm install",
+    "doc-rooted": "TD_BUILD_CTX=doc-rooted npm run",
     "fix-and-test": "echo 'RUNNING most FIXES AND TESTS...'; npm run fix-for-test && npm run test:website",
     "fix:format:diff": "npm run fix:format",
     "fix:format": "npm run -s _check:format -- --write && echo && npm run -s cd:docsy.dev fix:format",