From 267833b5a11732ec79e8e75a2d7b2334b04d496f Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Tue, 17 Feb 2026 08:10:16 -0500 Subject: [PATCH] Doc-rooted mounts and more --- docsy.dev/.gitignore | 3 + docsy.dev/config/_default/hugo.yaml | 2 + docsy.dev/config/_default/params.yaml | 2 +- docsy.dev/config/doc-rooted/hugo.yaml | 7 -- .../content/en/docs/best-practices/_index.md | 1 - docsy.dev/content/en/docs/content/_index.md | 1 - .../content/en/docs/content/navigation.md | 6 ++ .../get-started/docsy-as-module/_index.md | 1 - docsy.dev/package.json | 5 ++ docsy.dev/scripts/gen-doc-rooted-module.pl | 79 +++++++++++++++++++ package.json | 3 +- 11 files changed, 98 insertions(+), 12 deletions(-) delete mode 100644 docsy.dev/config/doc-rooted/hugo.yaml create mode 100644 docsy.dev/scripts/gen-doc-rooted-module.pl diff --git a/docsy.dev/.gitignore b/docsy.dev/.gitignore index c18d685e77..d65cccf9fe 100644 --- a/docsy.dev/.gitignore +++ b/docsy.dev/.gitignore @@ -3,3 +3,6 @@ /public resources/ tmp + +# Generated files +/config/doc-rooted/module.yaml diff --git a/docsy.dev/config/_default/hugo.yaml b/docsy.dev/config/_default/hugo.yaml index c08e0f1e82..a2565d85b8 100644 --- a/docsy.dev/config/_default/hugo.yaml +++ b/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 diff --git a/docsy.dev/config/_default/params.yaml b/docsy.dev/config/_default/params.yaml index 91bddcb74f..7c0183d221 100644 --- a/docsy.dev/config/_default/params.yaml +++ b/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 diff --git a/docsy.dev/config/doc-rooted/hugo.yaml b/docsy.dev/config/doc-rooted/hugo.yaml deleted file mode 100644 index 5c4f106b9c..0000000000 --- a/docsy.dev/config/doc-rooted/hugo.yaml +++ /dev/null @@ -1,7 +0,0 @@ -# This doc-rooted variant of the Docsy site overrides the existing home page, -# but Hugo doesn't seem to always resolve the conflict in the same way: locally -# I see the docs landing page win, but on Netlify I see the site home page win. -# Let's avoid the conflict by hiding the home page when building a doc-rooted -# site variant. This config isn't necessary for regular doc-rooted sites. - -disableKinds: [home] diff --git a/docsy.dev/content/en/docs/best-practices/_index.md b/docsy.dev/content/en/docs/best-practices/_index.md index d1f7c843ca..5f981f58a4 100644 --- a/docsy.dev/content/en/docs/best-practices/_index.md +++ b/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 diff --git a/docsy.dev/content/en/docs/content/_index.md b/docsy.dev/content/en/docs/content/_index.md index ebc59cb78b..d0d3d4d204 100644 --- a/docsy.dev/content/en/docs/content/_index.md +++ b/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 --- diff --git a/docsy.dev/content/en/docs/content/navigation.md b/docsy.dev/content/en/docs/content/navigation.md index 4a93234517..d6c2980f68 100644 --- a/docsy.dev/content/en/docs/content/navigation.md +++ b/docsy.dev/content/en/docs/content/navigation.md @@ -482,6 +482,10 @@ sidebar_root_for: self --- ``` +{{< comment >}} + +FIXME: Add examples under test and refer to them here. + Examples: | `sidebar_root_for` | Example | @@ -489,6 +493,8 @@ Examples: | `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. diff --git a/docsy.dev/content/en/docs/get-started/docsy-as-module/_index.md b/docsy.dev/content/en/docs/get-started/docsy-as-module/_index.md index 864b98ead2..40ef3b1bb0 100644 --- a/docsy.dev/content/en/docs/get-started/docsy-as-module/_index.md +++ b/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 diff --git a/docsy.dev/package.json b/docsy.dev/package.json index 32a3e81904..5f96834efe 100644 --- a/docsy.dev/package.json +++ b/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", diff --git a/docsy.dev/scripts/gen-doc-rooted-module.pl b/docsy.dev/scripts/gen-doc-rooted-module.pl new file mode 100644 index 0000000000..5f83e3563b --- /dev/null +++ b/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: " 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"; diff --git a/package.json b/package.json index ebc6d546a4..0cbb3aadaf 100644 --- a/package.json +++ b/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",