From 0bc1f6a146b49afa26b5433944931e67e477b2a9 Mon Sep 17 00:00:00 2001 From: Gareth Watts Date: Tue, 3 Nov 2020 12:54:27 -0600 Subject: [PATCH 1/3] Exclude search result page from page lists --- layouts/partials/section-index.html | 1 + 1 file changed, 1 insertion(+) diff --git a/layouts/partials/section-index.html b/layouts/partials/section-index.html index be3cbcd9c5..ded8e993df 100644 --- a/layouts/partials/section-index.html +++ b/layouts/partials/section-index.html @@ -1,5 +1,6 @@
{{ $pages := (where .Site.Pages "Section" .Section).ByWeight }} + {{ $pages = (where $pages "Type" "!=" "search") }} {{ $parent := .Page }} {{ if $parent.Params.no_list }} {{/* If no_list is true we don't show a list of subpages */}} From f61c44f9b2fd5c923fd93e98f3f2006fcff421b6 Mon Sep 17 00:00:00 2001 From: Gareth Watts Date: Tue, 3 Nov 2020 12:55:55 -0600 Subject: [PATCH 2/3] Make sidebar section tree also work for "just docs" sites This introduces no change in behaviour for the default case, but for sites that use cascade to render most pages as a "docs" type, it allows the tree to be correctly rooted from the home page (type docs itself) and also allows specific sections to act as their own separate root, by setting toc_root=true in their front matter. --- layouts/partials/sidebar-tree.html | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/layouts/partials/sidebar-tree.html b/layouts/partials/sidebar-tree.html index 3443e2c527..2a3111e4f7 100644 --- a/layouts/partials/sidebar-tree.html +++ b/layouts/partials/sidebar-tree.html @@ -23,7 +23,8 @@ {{ partial "navbar-lang-selector.html" . }}
{{ end }} - {{ template "section-tree-nav-section" (dict "page" . "section" .FirstSection "delayActive" $shouldDelayActive) }} + {{ $navRoot := cond (and (ne .Params.toc_root true) (eq .Site.Home.Type "docs")) .Site.Home .FirstSection }} + {{ template "section-tree-nav-section" (dict "page" . "section" $navRoot "delayActive" $shouldDelayActive) }} {{ define "section-tree-nav-section" }} @@ -42,12 +43,14 @@ {{ $pages := where (union $s.Pages $s.Sections).ByWeight ".Params.toc_hide" "!=" true }} {{ $pages := $pages | first 50 }} {{ range $pages }} - {{ if .IsPage }} - {{ $mid := printf "m-%s" (.RelPermalink | anchorize) }} - {{ $active := eq . $p }} - {{ .LinkTitle }} - {{ else }} - {{ template "section-tree-nav-section" (dict "page" $p "section" .) }} + {{ if (not (and (eq $s $p.Site.Home) (eq .Params.toc_root true))) }} + {{ if .IsPage }} + {{ $mid := printf "m-%s" (.RelPermalink | anchorize) }} + {{ $active := eq . $p }} + {{ .LinkTitle }} + {{ else }} + {{ template "section-tree-nav-section" (dict "page" $p "section" .) }} + {{ end }} {{ end }} {{ end }} From aa71fc4cebb591fed719c8c8329a0befe4fc1156 Mon Sep 17 00:00:00 2001 From: Gareth Watts Date: Wed, 11 Nov 2020 12:42:55 -0600 Subject: [PATCH 3/3] Add alt site structure docs --- .../content/en/docs/Adding content/content.md | 46 ++++++++++++++++++- 1 file changed, 45 insertions(+), 1 deletion(-) diff --git a/userguide/content/en/docs/Adding content/content.md b/userguide/content/en/docs/Adding content/content.md index 2c273bfa13..b0860b306b 100644 --- a/userguide/content/en/docs/Adding content/content.md +++ b/userguide/content/en/docs/Adding content/content.md @@ -48,13 +48,57 @@ Alternatively, create your own page template for your new section in your projec 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 + +As noted above, by default your site has a home page (using the `_default` layout), a docs section under `/docs/`, a blog section under `/blog/` and a community section under `/community/`. [The type](https://gohugo.io/content-management/types/) of each section (which determines the layout it uses) matches its directory name. + +In some cases, you may want to have a different directory structure, but still make use of Docsy's layouts. A common example is for a "docs site", where most of the pages (including the home page) use the docs layout, or perhaps you'd rather have a `/news/` directory treated 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": + +```yaml +--- +title: "Latest News" +linkTitle: "News" +menu: + main: + weight: 30 + +cascade: +- type: "blog" +--- +``` + +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": + +```yaml +--- +title: "My Wonderful Site" + +cascade: +- type: "blog" + toc_root: true + _target: + path: "/news/**" +- type: "docs" + _target: + path: "/**" +--- +``` + +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. + +An example docs-based site that uses this technique can be found at the [mostly docs](https://github.com/gwatts/mostlydocs/) repo. + ## Page frontmatter Each page file in a Hugo site has metadata frontmatter that tells Hugo about the page. You specify page frontmatter in TOML, YAML, or JSON (our example site and this site use YAML). Use the frontmatter to specify the page title, description, creation date, link title, template, menu weighting, and even any resources such as images used by the page. You can see a complete list of possible page frontmatter in [Front Matter](https://gohugo.io/content-management/front-matter/). For example, here's the frontmatter for this page: -``` +```yaml --- title: "Adding Content" linkTitle: "Adding Content"