diff options
author | Gareth Watts <gareth@omnipotent.net> | 2020-11-11 21:42:55 +0300 |
---|---|---|
committer | Gareth Watts <gareth@omnipotent.net> | 2020-11-11 21:42:55 +0300 |
commit | aa71fc4cebb591fed719c8c8329a0befe4fc1156 (patch) | |
tree | 5d7a529885cf1292549c056c5e9da3f85c4a7311 /userguide/content | |
parent | f61c44f9b2fd5c923fd93e98f3f2006fcff421b6 (diff) |
Add alt site structure docs
Diffstat (limited to 'userguide/content')
-rw-r--r-- | userguide/content/en/docs/Adding content/content.md | 46 |
1 files changed, 45 insertions, 1 deletions
diff --git a/userguide/content/en/docs/Adding content/content.md b/userguide/content/en/docs/Adding content/content.md index 2c273bf..b0860b3 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" |