diff --git a/docsy.dev/config/_default/params.yaml b/docsy.dev/config/_default/params.yaml index 9aa830b33..0c6e143d0 100644 --- a/docsy.dev/config/_default/params.yaml +++ b/docsy.dev/config/_default/params.yaml @@ -9,7 +9,7 @@ tdVersion: latest: &tdLatestVers v0.14.3 dev: &tdDevVers v0.14.4-dev - buildId: &tdBuildId 023-over-main-3bcb7385 + buildId: &tdBuildId 024-over-main-500ee239 version: *tdDevVers version_menu: *tdDevVers diff --git a/docsy.dev/config/doc-rooted/params.yaml b/docsy.dev/config/doc-rooted/params.yaml index a3b37be96..02420e5e1 100644 --- a/docsy.dev/config/doc-rooted/params.yaml +++ b/docsy.dev/config/doc-rooted/params.yaml @@ -3,7 +3,7 @@ tdVersion: latest: &tdLatestVers v0.14.3 dev: &tdDevVers v0.14.4-dev - buildId: &tdBuildId 023-over-main-3bcb7385 + buildId: &tdBuildId 024-over-main-500ee239 version: &tdDocRootedVers Doc-rooted of Next version_menu: *tdLatestVers diff --git a/docsy.dev/config/production/params.yaml b/docsy.dev/config/production/params.yaml index dd5d15c6b..9ea23a883 100644 --- a/docsy.dev/config/production/params.yaml +++ b/docsy.dev/config/production/params.yaml @@ -3,7 +3,7 @@ tdVersion: latest: &tdLatestVers v0.14.3 dev: &tdDevVers v0.14.4-dev - buildId: &tdBuildId 023-over-main-3bcb7385 + buildId: &tdBuildId 024-over-main-500ee239 version: *tdLatestVers version_menu: *tdLatestVers diff --git a/docsy.dev/content/en/docs/content/adding-content.md b/docsy.dev/content/en/docs/content/adding-content.md index 9491e2906..bd81e737c 100644 --- a/docsy.dev/content/en/docs/content/adding-content.md +++ b/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 +{{%_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 diff --git a/package.json b/package.json index a3fb47d90..62a8a3e9a 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "docsy", - "version": "0.14.4-dev+023-over-main-3bcb7385", + "version": "0.14.4-dev+024-over-main-500ee239", "repository": "github:google/docsy", "homepage": "https://www.docsy.dev", "license": "Apache-2.0",