Merge branch 'main' into patch-1

Author: putku45

.markdownlint-cli2.yaml

@@ -1,5 +1,8 @@
 # cSpell:ignore docsy github lookandfeel iconsimages
 
+customRules:
+  - ./scripts/_md-rules/link-rules.mjs
+
 globs:
   - '!docsy.dev/**'
   - '!layouts/**'

.markdownlint.yaml

@@ -15,3 +15,10 @@ no-inline-html: false
 no-trailing-punctuation: false
 no-trailing-spaces: {  br_spaces: 0, strict: true}
 # table-column-style: false
+
+# Link-validation rules (from scripts/_md-rules/link-rules.mjs)
+
+no-docsy-dev-external-urls:
+  pattern: 'https?://(?:www\.)?docsy\.dev/'
+  message: Use a site-relative path instead of the full docsy.dev URL.
+  replace: '/'

CHANGELOG.md

@@ -1,5 +1,7 @@
 # Changelog
 
+<!-- markdownlint-disable no-docsy-dev-external-urls -->
+
 The changelog is published online, see
 [Changelog](https://www.docsy.dev/project/about/changelog/) or the
 [page source](docsy.dev/content/en/project/about/changelog.md).

CONTRIBUTING.md

@@ -1,5 +1,7 @@
 # Contributing
 
+<!-- markdownlint-disable no-docsy-dev-external-urls -->
+
 The contributing page is published online, see
 [Contributing](https://www.docsy.dev/docs/contributing/) or the
 [page source](docsy.dev/content/en/docs/contributing.md).

README.md

@@ -1,5 +1,7 @@
 # Docsy
 
+<!-- markdownlint-disable no-docsy-dev-external-urls -->
+
 Docsy is a [Hugo](https://gohugo.io) theme for technical documentation sets,
 providing simple navigation, site structure, and more.
 
@@ -106,9 +108,6 @@ This project is licensed under the Apache License 2.0, see
 [deploys]: https://app.netlify.com/sites/docsydocs/deploys
 [main-preview]: https://main--docsydocs.netlify.app/
 [netlify]: https://netlify.com
-
-<!-- FIXME: once 0.14.0 is released, update the link to the changelog page -->
-
 [official-support]:
   https://www.docsy.dev/project/about/changelog/#official-support
 [releases]: https://github.com/google/docsy/releases

assets/scss/td/_nav.scss

@@ -162,6 +162,12 @@ $td-link-underline-offsets: (
           content: ' (latest)';
         }
       }
+
+      &-next {
+        &::after {
+          content: ' (next)';
+        }
+      }
     }
   }
 

docsy.dev/config/_default/params.yaml

@@ -6,31 +6,26 @@
 # version:
 #   status: archived # Then fetch include
 
-version: &docsyVersion 0.14.4-dev
-tdBuildId: 020-over-main-4a09247b
-versionLatest: &versionLatest v0.14.3
-version_menu: *docsyVersion
+tdVersion:
+  latest: &tdLatestVers v0.14.3
+  dev: &tdDevVers v0.14.4-dev
+  buildId: &tdBuildId 024-over-main-500ee239
+
+version: *tdDevVers
+version_menu: *tdDevVers
 version_menu_pagelinks: true
 versions:
-  # - name: '**About**'
-  #   url: /project
-  #   pagelinks: false
-  # - name: ---
   - name: '**Versions**'
-  - name: Next
-    version: *docsyVersion
-    # TODO: use https://next.docsy.dev once it's available
-    url: https://main--docsydocs.netlify.app
-  - version: *versionLatest
-    url: https://www.docsy.dev
+  - version: *tdDevVers
+    # kind: next
+    pagelinks: true
+    url: https://main--docsydocs.netlify.app # TODO: use next.docsy.dev once available
+  - version: *tdLatestVers
     kind: latest
+    url: https://www.docsy.dev
   - name: ---
   - 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
+  - name: Doc-rooted (experimental)
     kind: home
-  # - name: Goldydocs
-  #   url: https://example.docsy.dev
-  #   pagelinks: false
+    pagelinks: false # TODO: drop this once /docs/* redirects are implemented
+    url: https://doc-rooted--docsydocs.netlify.app

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

@@ -1,13 +1,26 @@
 # cSpell:ignore pagelinks
 
-version: &docsyVersion 0.14.3
-version_menu: *docsyVersion
+tdVersion:
+  latest: &tdLatestVers v0.14.3
+  dev: &tdDevVers v0.14.4-dev
+  buildId: &tdBuildId 024-over-main-500ee239
+
+version: &tdDocRootedVers Doc-rooted of Next
+version_menu: *tdLatestVers
+version_menu_pagelinks: false
 versions:
+  - name: '**Versions**'
   - name: Next
-    kind: next
-    url: https://main--docsydocs.netlify.app/
-    pagelinks: false
-  - version: *docsyVersion
+    version: *tdDevVers
+    # kind: next
+    url: https://main--docsydocs.netlify.app
+  - version: *tdLatestVers
     kind: latest
     url: https://www.docsy.dev
-    pagelinks: false
+  - name: ---
+  - name: '**Variant**'
+  - name: Doc-rooted (experimental)
+    version: *tdDocRootedVers
+    kind: home
+    pagelinks: false # TODO: drop this once /docs/* redirects are implemented
+    url: https://doc-rooted--docsydocs.netlify.app

docsy.dev/config/production/params.yaml

@@ -1,13 +1,18 @@
 # cSpell:ignore pagelinks
 
-version: &docsyVersion 0.14.3
-version_menu: *docsyVersion
+tdVersion:
+  latest: &tdLatestVers v0.14.3
+  dev: &tdDevVers v0.14.4-dev
+  buildId: &tdBuildId 024-over-main-500ee239
+
+version: *tdLatestVers
+version_menu: *tdLatestVers
 versions:
+  - name: '**Versions**'
   - name: Next
-    kind: next
-    url: https://main--docsydocs.netlify.app/
-    pagelinks: true
-  - version: *docsyVersion
+    version: *tdDevVers
+    # kind: next
+    url: https://main--docsydocs.netlify.app
+  - version: *tdLatestVers
     kind: latest
     url: https://www.docsy.dev
-    pagelinks: true

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

@@ -136,6 +136,8 @@ about how to add content and use each of Docsy's templates.
 
 ## Doc-rooted sites <a id="alternative-site-structure"></a>
 
+{{%_param BADGE EXPERIMENTAL info %}}
+
 Docsy supports documentation-first websites through a **doc-rooted** site
 structure, where:
 
@@ -147,7 +149,7 @@ structure, where:
 As a consequence, the `docs` section landing page becomes the site home page. A
 doc-rooted site has the following benefits:
 
-- Produces cleaner, documentation-focused URLs (no `/docs/` prefix).
+- Produces simpler, documentation-focused URLs (no `/docs/` prefix).
 - Avoids the need to create a custom home page using [blocks][] shortcodes or
   HTML.
 
@@ -162,25 +164,37 @@ permalinks:
     docs: /:sections[1:]
 ```
 
-> [!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/`.
+Because the docs section landing page now serves as the home page, you need to
+add extra configuration to avoid "Duplicate target paths" warnings and avoid
+render conflicts with the site-root index file.
+
+Add the following front matter to each site root index file (one per language in
+multilingual sites):
+
+```yaml
+build: { render: link }
+```
 
 For an example of a doc-rooted variant of this site, see the [Doc-rooted
 example][] variant.
 
 [Doc-rooted example]: https://doc-rooted--docsydocs.netlify.app
 
-> [!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.
+### Check for path conflicts
+
+If your doc-rooted site has non-docs pages (such as blog or community pages),
+check for possible root-level path conflicts between docs and non-docs pages. To
+have Hugo report duplicate path warnings when building your site, use the
+`--printPathWarnings` flag.
+
+### 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 old `cascade` entries and use the
+configuration described earlier in this section.
 
 ## Page front matter