Add doc-rooted site example version, update guidance (#2563)

Author: chalin

assets/scss/td/_nav.scss

@@ -11,6 +11,17 @@ $td-link-underline-offsets: (
   4: 0.5em,
 ) !default;
 
+@mixin td-navbar-dropdown-item-icon($fa-icon) {
+  &::before {
+    content: fa-content($fa-icon);
+    font: var(--fa-font-solid);
+    position: absolute;
+    left: 0.75rem;
+    top: 50%;
+    transform: translateY(-50%);
+  }
+}
+
 .td-navbar {
   @extend .navbar;
   @extend .navbar-expand;
@@ -137,13 +148,19 @@ $td-link-underline-offsets: (
       position: relative;
       padding-left: 2.5rem;
 
-      &.active::before {
-        font: var(--fa-font-solid);
-        content: fa-content($fa-var-check);
-        position: absolute;
-        left: 0.75rem;
-        top: 50%;
-        transform: translateY(-50%);
+      &.active {
+        @include td-navbar-dropdown-item-icon($fa-var-check);
+      }
+
+      &-home {
+        @include td-navbar-dropdown-item-icon($fa-var-house);
+      }
+
+      &-latest {
+        font-weight: $font-weight-semibold;
+        &::after {
+          content: ' (latest)';
+        }
       }
     }
   }

docsy.dev/hugo.yaml docsy.dev/config/_default/hugo.yamldocsy.dev/hugo.yaml renamed to docsy.dev/config/_default/hugo.yaml

@@ -60,7 +60,6 @@ params:
     from_year: 2018
     to_year: present
   privacy_policy: https://policies.google.com/privacy
-  archived_version: false
   github_repo: https://github.com/google/docsy
   github_project_repo: https://github.com/google/docsy
   github_subdir: docsy.dev
@@ -169,10 +168,6 @@ security:
       # Netlify build env var
       - ^(BRANCH|BUILD_ID|COMMIT_REF|CONTEXT|DEPLOY_ID|NETLIFY|PULL_REQUEST|REVIEW_ID)$
 
-sites: &sites
-  matrix:
-    languages: [en, fr]
-
 module:
   hugoVersion:
     extended: true
@@ -185,7 +180,7 @@ module:
     # English content for en and as fallback for fr (other pages)
     - source: content/en
       target: content
-      sites: *sites
+      sites: &sites { matrix: { languages: [en, fr] } }
     # 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,18 +7,30 @@
 #   status: archived # Then fetch include
 
 version: &docsyVersion 0.14.3-dev
-tdBuildId: 006-over-main-d125b877
+tdBuildId: 008-over-main-8a63d915
 versionLatest: &versionLatest v0.14.2
 version_menu: *docsyVersion
 version_menu_pagelinks: true
 versions:
+  # - name: '**About**'
+  #   url: /project
+  #   pagelinks: false
+  # - name: ---
+  - name: '**Versions**'
   - name: Next
     version: *docsyVersion
-    url: https://main--docsydocs.netlify.app
     # TODO: use https://next.docsy.dev once it's available
-    # kind: next
+    url: https://main--docsydocs.netlify.app
   - version: *versionLatest
     url: https://www.docsy.dev
-    # kind: latest
+    kind: latest
   - name: ---
-  - name: More coming soon...
+  - name: '**Variant**'
+  - name: Doc-rooted
+    url: https://doc-rooted--docsydocs.netlify.app
+    # TODO: implement /docs/* redirects for doc-rooted site, then drop pagelinks:false
+    pagelinks: false
+    kind: home
+  # - name: Goldydocs
+  #   url: https://example.docsy.dev
+  #   pagelinks: false

docsy.dev/config/doc-rooted/permalinks.yaml

@@ -0,0 +1,4 @@
+page:
+  docs: /:sections[1:]/:slug/
+section:
+  docs: /:sections[1:]

docsy.dev/content/en/docs/content/adding-content.md

@@ -71,7 +71,7 @@ site content root. Hugo automatically applies the appropriate **template** for
 that section, depending on which folder the content is in. For example, this
 page is in the `docs` subdirectory of the site's content root directory
 `content/en/`, so Hugo automatically applies the `docs` template. You can
-override this by explicitly specifying a template or content type for a
+override this by explicitly specifying a template or [content type][] for a
 particular page.
 
 If you've copied the example site, you already have appropriately named
@@ -134,151 +134,53 @@ You can find out much more about how Hugo page layouts work in
 [Hugo Templates](https://gohugo.io/templates/). The rest of this page tells you
 about how to add content and use each of Docsy's templates.
 
-### Alternative site structure and docs-only sites {#alternative-site-structure}
+## Doc-rooted sites <a id="alternative-site-structure"></a>
 
-As noted above, Docsy assumes that (by default) your site has:
+Docsy supports documentation-first websites through a **doc-rooted** site
+structure, where:
 
-- Home page
-- Docs section under `/docs/`
-- Blog section under `/blog/`
-- Community section under `/community/`
+- Documentation pages are published at the site root (`/`) rather than under the
+  `/docs/` path prefix.
+- Page files remain in the `docs` section directory, for example `content/docs/`
+  or `content/en/docs/`.
 
-The [content type][] of each section determines the layout Hugo uses for that
-section.
+As a consequence, the `docs` section landing page becomes the site home page. A
+doc-rooted site has the following benefits:
 
-[content type]: https://gohugo.io/quick-reference/glossary/#content-type
-
-You may want to have a different site structure for your project while still
-making use of Docsy's layouts. A common example is for a **_docs-only_** site,
-where all of the pages (including the homepage) use the `docs` layout. In such a
-site, you might want to have `/news/` pages formatted with the blog layout.
-
-Since Hugo 0.76, this has become practical without copying layouts to your site,
-or having to specify `type: blog` on every single page by making use of
-[target specific cascading front matter](https://gohugo.io/content-management/front-matter/#target-specific-pages).
-
-For example, for the `/news/` section, you can specify the following front
-matter in the index page which will change the type of the section and
-everything below it to "blog":
-
-<!-- markdownlint-disable -->
-<!-- prettier-ignore-start -->
-{{< tabpane >}}
-{{< tab header="Front matter:" disabled=true />}}
-{{< tab header="toml" lang="toml" >}}
-+++
-title = "Latest News"
-linkTitle = "News"
-
-[menu.main]
-weight = 30
-
-[[cascade]]
-type = "blog"
-+++
-{{< /tab >}}
-{{< tab header="yaml" lang="yaml" >}}
----
-title: "Latest News"
-linkTitle: "News"
-menu:
-  main:
-    weight: 30
-
-cascade:
-  - type: "blog"
----
-{{< /tab >}}
-{{< tab header="json" lang="json" >}}
-{
-  "title": "Latest News",
-  "linkTitle": "News",
-  "menu": {
-    "main": {
-      "weight": 30
-    }
-  },
-  "cascade": [
-    {
-      "type": "blog"
-    }
-  ]
-}
-{{< /tab >}}
-{{< /tabpane >}}
-<!-- prettier-ignore-end -->
-<!-- markdownlint-restore -->
+- Produces cleaner, documentation-focused URLs (no `/docs/` prefix).
+- Avoids the need to create a custom home page using [blocks][] shortcodes or
+  HTML.
 
-If you want to create a "docs" site, specifying something like the following in
-the top level `_index.md` will set all top level sections to be treated as
-"docs", except for "news":
+To create a doc-rooted site, redefine the `docs` section [permalinks][] in your
+[site configuration][] as follows (YAML format shown):
 
-<!-- markdownlint-disable -->
-<!-- prettier-ignore-start -->
-{{< tabpane >}}
-{{< tab header="Front matter:" disabled=true />}}
-{{< tab header="toml" lang="toml" >}}
-+++
-title = "My Wonderful Site"
-
-[[cascade]]
-type = "blog"
-toc_root = true
-
-  [cascade._target]
-  path = "/news/**"
+```yaml
+permalinks:
+  page:
+    docs: /:sections[1:]/:slug/
+  section:
+    docs: /:sections[1:]
+```
 
-[[cascade]]
-type = "docs"
+> [!CAUTION]
+>
+> Check for root-level URL path conflicts between doc and non-doc sections or
+> pages (for example, `/blog/` and `/community/`). If conflicts exist, rename
+> the conflicting non-doc paths or keep docs under `/docs/`.
 
-  [cascade._target]
-  path = "/**"
-+++
-{{< /tab >}}
-{{< tab header="yaml" lang="yaml" >}}
----
-title: "My Wonderful Site"
-
-cascade:
-  - type: "blog"
-    toc_root: true
-    _target:
-    path: "/news/**"
-  - type: "docs"
-    _target:
-    path: "/**"
----
-{{< /tab >}}
-{{< tab header="json" lang="json" >}}
-{
-  "title": "My Wonderful Site",
-  "cascade": [
-    {
-      "type": "blog",
-      "toc_root": true,
-      "_target": {
-        "path": "/news/**"
-      }
-    },
-    {
-      "type": "docs",
-      "_target": {
-        "path": "/**"
-      }
-    }
-  ]
-}
-{{< /tab >}}
-{{< /tabpane >}}
-<!-- prettier-ignore-end -->
-<!-- markdownlint-restore -->
+For an example of a doc-rooted variant of this site, see the [Doc-rooted
+example][] variant.
 
-Note the addition of `toc_root` here. Setting that to true for a section causes
-it to be treated as a separate part of the site, with its own left hand
-navigation menu.
+[Doc-rooted example]: https://doc-rooted--docsydocs.netlify.app
 
-An example docs-based site that uses this technique can be found at the
-[mostly docs](https://github.com/gwatts/mostlydocs/) repo.
+> [!NOTE] Legacy _docs-only_ setup
+>
+> Earlier versions of this page described a docs-only configuration that used a
+> front matter `cascade` to set page `type` values.
+>
+> That approach is no longer supported and can produce incorrect behavior. If
+> you are migrating from that setup, remove the `cascade` rule and configure
+> doc-rooted permalinks as described above.
 
 ## Page front matter
 
@@ -290,37 +192,31 @@ resources such as images used by the page. You can see a complete list of
 possible page front matter in
 [Front Matter](https://gohugo.io/content-management/front-matter/).
 
-For example, here's the front matter for this page:
+For example:
 
 <!-- markdownlint-disable -->
 <!-- prettier-ignore-start -->
 {{< tabpane >}}
 {{< tab header="Front matter:" disabled=true />}}
 {{< tab header="toml" lang="toml" >}}
 +++
-title = "Adding Content"
-linkTitle = "Adding Content"
-weight = 1
-description = '''
-Add different types of content to your Docsy site.
-'''
+title = "About Docsy"
+linkTitle = "About"
+description = "Docsy is ..."
 +++
 {{< /tab >}}
 {{< tab header="yaml" lang="yaml" >}}
 ---
-title: "Adding Content"
-linkTitle: "Adding Content"
-weight: 1
-description: >
-  Add different types of content to your Docsy site.
+title: About Docsy
+linkTitle: About
+description: Docsy is ...
 ---
 {{< /tab >}}
 {{< tab header="json" lang="json" >}}
 {
-  "title": "Adding Content",
-  "linkTitle": "Adding Content",
-  "weight": 1,
-  "description": "Add different types of content to your Docsy site.\n"
+  "title": "About Docsy",
+  "linkTitle": "About",
+  "description": "Docsy is ..."
 }
 {{< /tab >}}
 {{< /tabpane >}}
@@ -1029,13 +925,17 @@ To learn more about configuring sitemaps, see [Sitemap Templates][].
 
 [alerts]: https://gohugo.io/render-hooks/blockquotes/#alerts
 [attributes]: https://gohugo.io/content-management/markdown-attributes/
+[blocks]: /docs/content/shortcodes/#blocks
 [commonmark]: https://spec.commonmark.org/
+[content type]: https://gohugo.io/quick-reference/glossary/#content-type
 [Emojis]: https://gohugo.io/quick-reference/emojis/
 [extensions]: https://gohugo.io/configuration/markup/#extensions
 [formats]: https://gohugo.io/content-management/formats/
 [GFM]: https://github.github.com/gfm/
 [Goldmark]: https://github.com/yuin/goldmark
 [Look and Feel]: /docs/content/lookandfeel/
+[permalinks]: https://gohugo.io/configuration/permalinks/
 [render hooks]: https://gohugo.io/render-hooks/introduction/
 [shortcodes]: https://gohugo.io/content-management/shortcodes/
+[site configuration]: https://gohugo.io/configuration/introduction/
 [Sitemap Templates]: https://gohugo.io/templates/sitemap-template/

docsy.dev/package.json

@@ -8,8 +8,9 @@
     "_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\"",
-    "_hugo-dev": "npm run _hugo -- --logLevel info -e dev -DFE",
-    "_hugo": "hugo --cleanDestinationDir --themesDir ../..",
+    "_hugo-dev-test": "npm run _hugo-dev -- --templateMetrics --templateMetricsHints",
+    "_hugo-dev": "cross-env npm run _hugo -- -e \"${HUGO_ENVIRONMENT:-development}\" -DFE",
+    "_hugo": "hugo --cleanDestinationDir --logLevel info --themesDir ../..",
     "_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}\"",