Content and Customization

• 1: Adding Content
• 2: Look and Feel
• 3: Navigation and Search
• 4: Doc Versioning
• 5: Docsy Shortcodes
• 6: Logos and Images
• 7: Print Support
• 8: Analytics, User Feedback, and SEO
• 9: Repository Links
• 10: Taxonomy Support
• 11: Diagrams and Formulae

1 - Adding Content

So you’ve got a new Hugo website with Docsy, now it’s time to add some content! This page tells you how to use the theme to add and structure your site content.

Content root directory

You add content for your site under the content root directory of your Hugo site project - either content/ or a language-specific root like content/en/. The main exception here is static files that you don’t want built into your site: you can find out more about where you add these below in Adding static content. The files in your content root directory are typically grouped in subdirectories corresponding to your site’s sections and templates, which we’ll look at in Content sections and templates.

You can find out more about Hugo directory structure in Directory Structure Explained.

Content sections and templates

Hugo builds your site pages using the content files you provide plus any templates provided by your site’s theme. These templates (or “layouts” in Hugo terminology) include things like your page’s headers, footers, navigation, and links to stylesheets: essentially, everything except your page’s specific content. The templates in turn can be made up of partials: little reusable snippets of HTML for page elements like headers, search boxes, and more.

Because most technical documentation sites have different sections for different types of content, the Docsy theme comes with the following templates for top-level site sections that you might need:

• docs is for pages in your site’s Documentation section.
• blog is for pages in your site’s Blog.
• community is for your site’s Community page.

It also provides a default “landing page” type of template with the site header and footer, but no left nav, that you can use for any other section. In this site and our example site it’s used for the site home page and the About page.

Each top-level section in your site corresponds to a directory in your 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 particular page.

If you’ve copied the example site, you already have appropriately named top-level section directories for using Docsy’s templates, each with an index page ( _index.md or index.html) page for users to land on. These top-level sections also appear in the example site’s top-level menu.

Custom sections

If you’ve copied the example site and don’t want to use one of the provided content sections, just delete the appropriate content subdirectory. Similarly, if you want to add a top-level section, just add a new subdirectory, though you’ll need to specify the layout or content type explicitly in the frontmatter of each page if you want to use any existing Docsy template other than the default one. For example, if you create a new directory content/en/amazing and want one or more pages in that custom section to use Docsy’s docs template, you add type: docs to the frontmatter of each page:

• Front matter:
• toml
• yaml
• json

+++
title = "My amazing new section"
weight = 1
type = "docs"
description = '''
A special section with a docs layout.
'''
+++

---
title: "My amazing new section"
weight: 1
type: docs
description: >
  A special section with a docs layout.  
---

{
  "title": "My amazing new section",
  "weight": 1,
  "type": "docs",
  "description": "A special section with a docs layout.\n"
}

Alternatively, create your own page template for your new section in your project’s layouts directory based on one of the existing templates.

You can find out much more about how Hugo page layouts work in Hugo 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 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.

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”:

• Front matter:
• toml
• yaml
• json

+++
title = "Latest News"
linkTitle = "News"

[menu.main]
weight = 30

[[cascade]]
type = "blog"
+++

---
title: "Latest News"
linkTitle: "News"
menu:
  main:
    weight: 30

cascade:
  - type: "blog"
---

{
  "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”:

• Front matter:
• toml
• yaml
• json

+++
title = "My Wonderful Site"

[[cascade]]
type = "blog"
toc_root = true

  [cascade._target]
  path = "/news/**"

[[cascade]]
type = "docs"

  [cascade._target]
  path = "/**"
+++

---
title: "My Wonderful Site"

cascade:
  - type: "blog"
    toc_root: true
    _target:
    path: "/news/**"
  - type: "docs"
    _target:
    path: "/**"
---

{
  "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 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.

For example, here’s the frontmatter for this page:

• Front matter:
• toml
• yaml
• json

+++
title = "Adding Content"
linkTitle = "Adding Content"
weight = 1
description = '''
Add different types of content to your Docsy site.
'''
+++

---
title: "Adding Content"
linkTitle: "Adding Content"
weight: 1
description: >
  Add different types of content to your Docsy site.  
---

{
  "title": "Adding Content",
  "linkTitle": "Adding Content",
  "weight": 1,
  "description": "Add different types of content to your Docsy site.\n"
}

The minimum frontmatter you need to provide is a title: everything else is up to you! However, if you leave out the page weight, your navigation may get a little disorganized. You may also want to include description since Docsy uses that to generate the meta description tag used by search engines. See Search Engine Optimization (SEO) meta tags for details.

Page contents and markup

By default you create pages in a Docsy site as simple Markdown or HTML files with page frontmatter, as described above. As of version 0.100, Goldmark is the only Markdown parser supported by Hugo.

[markup]
  [markup.goldmark]
    [markup.goldmark.renderer]
      unsafe = true

markup:
  goldmark:
    renderer:
      unsafe: true

{
  "markup": {
    "goldmark": {
      "renderer": {
        "unsafe": true
      }
    }
  }
}

In addition to your marked-up text, you can also use Hugo and Docsy’s shortcodes: reusable chunks of HTML that you can use to quickly build your pages. Find out more about shortcodes in Docsy Shortcodes.

Working with links

Hugo lets you specify links using normal Markdown syntax, though remember that you need to specify links relative to your site’s root URL, and that relative URLs are left unchanged by Hugo in your site’s generated HTML.

Alternatively you can use Hugo’s helper ref and relref shortcodes for creating internal links that resolve to the correct URL. However, be aware this means your links will not appear as links at all if a user views your page outside your generated site, for example using the rendered Markdown feature in GitHub’s web UI.

You can find (or add!) tips and gotchas for working with Hugo links in Hugo Tips.

Content style

We don’t mandate any particular style for your page contents. However, if you’d like some guidance on how to write and format clear, concise technical documentation, we recommend the Google Developer Documentation Style Guide, particularly the Style Guide Highlights.

Page bundles

You can create site pages as standalone files in their section or subsection directory, or as folders where the content is in the folder’s index page. Creating a folder for your page lets you bundle images and other resources together with the content.

You can see examples of both approaches in this and our example site. For example, the source for this page is just a standalone file /content/en/docs/adding-content.md. However the source for Docsy Shortcodes in this site lives in /content/en/docs/adding-content/shortcodes/index.md, with the image resource used by the page in the same /shortcodes/ directory. In Hugo terminology, this is called a leaf bundle because it’s a folder containing all the data for a single site page without any child pages (and uses index.md without an underscore).

You can find out much more about managing resources with Hugo bundles in Page Bundles.

Adding docs and blog posts

The template you’ll probably use most often is the docs template (as used in this page) or the very similar blog template. Both these templates include:

• a left nav
• GitHub links (populated from your site config) for readers to edit the page or create issues
• a page menu

as well as the common header and footer used by all your site’s pages. Which template is applied depends on whether you’ve added the content to the blog or docs content directory. You can find out more about how the nav and page menu are created in Navigation and Search.

Organizing your documentation

While Docsy’s top-level sections let you create site sections for different types of content, you may also want to organize your docs content within your docs section. For example, this site’s docs section directory has multiple subdirectories for Getting Started, Content and Customization, and so on. Each subdirectory has an _index.md (it could also be an _index.html), which acts as a section index page and tells Hugo that the relevant directory is a subsection of your docs.

Docsy’s docs layout gives you a left nav pane with an autogenerated nested menu based on your docs file structure. Each standalone page or subsection _index.md or _index.html page in the docs/ directory gets a top level menu item, using the link name and weight metadata from the page or index.

To add docs to a subsection, just add your page files to the relevant subdirectory. Any pages that you add to a subsection in addition to the subsection index page will appear in a submenu (look to the left to see one in action!), again ordered by page weight. Find out more about adding Docsy’s navigation metadata in Navigation and Search

If you’ve copied the example site, you’ll already have some suggested subdirectories in your docs directory, with guidance for what types of content to put in them and some example Markdown pages. You can find out more about organizing your content with Docsy in Organizing Your Content.

Docs section landing pages

By default a docs section landing page (the _index.md or _index.html in the section directory) uses a layout that adds a formatted list of links to the pages in the section, with their frontmatter descriptions. The Content and Customization landing page in this site is a good example.

To display a simple bulleted list of links to the section’s pages instead, specify simple_list: true in the landing page’s frontmatter:

• Front matter:
• toml
• yaml
• json

+++
title = "Simple List Page"
simple_list = true
weight = 20
+++

---
title: "Simple List Page"
simple_list: true
weight: 20
---

{
  "title": "Simple List Page",
  "simple_list": true,
  "weight": 20
}

To display no links at all, specify no_list: true in the landing page’s frontmatter:

• Front matter:
• toml
• yaml
• json

+++
title = "No List Page"
no_list = true
weight = 20
+++

---
title: "No List Page"
no_list: true
weight: 20
---

{
  "title": "No List Page",
  "no_list": true,
  "weight": 20
}

Organizing your blog posts

Docsy’s blog layout also gives you a left nav menu (like the docs layout), and a list-type index page for your blog that’s applied to /blog/_index.md and automatically displays snippets of all your recent posts in reverse chronological order.

To create different blog categories to organize your posts, create subfolders in blog/. For instance, in our example site we have news and releases. Each category needs to have its own _index.md or _index.html landing page file specifying the category title for it to appear properly in the left nav and top-level blog landing page. Here’s the index page for releases:

• Front matter:
• toml
• yaml
• json

+++
title = "New Releases"
linkTitle = "Releases"
weight = 20
+++

---
title: "New Releases"
linkTitle: "Releases"
weight: 20
---

{
  "title": "New Releases",
  "linkTitle": "Releases",
  "weight": 20
}

To add author and date information to blog posts, add them to the page frontmatter:

• Front matter:
• toml
• yaml
• json

+++
date = 2018-10-06T00:00:00.000Z
title = "Easy documentation with Docsy"
linkTitle = "Announcing Docsy"
description = "The Docsy Hugo theme lets project maintainers and contributors focus on content, not on reinventing a website infrastructure from scratch"
author = "Riona MacNamara"

[[resources]]
src = "**.{png,jpg}"
title = "Image #:counter"

  [resources.params]
  byline = "Photo: Riona MacNamara / CC-BY-CA"
+++

---
date: 2018-10-06
title: "Easy documentation with Docsy"
linkTitle: "Announcing Docsy"
description: "The Docsy Hugo theme lets project maintainers and contributors focus on content, not on reinventing a website infrastructure from scratch"
author: Riona MacNamara
resources:
  - src: "**.{png,jpg}"
    title: "Image #:counter"
    params:
    byline: "Photo: Riona MacNamara / CC-BY-CA"
---

{
  "date": "2018-10-06T00:00:00.000Z",
  "title": "Easy documentation with Docsy",
  "linkTitle": "Announcing Docsy",
  "description": "The Docsy Hugo theme lets project maintainers and contributors focus on content, not on reinventing a website infrastructure from scratch",
  "author": "Riona MacNamara",
  "resources": [
    {
      "src": "**.{png,jpg}",
      "title": "Image #:counter",
      "params": {
        "byline": "Photo: Riona MacNamara / CC-BY-CA"
      }
    }
  ]
}

If you’ve copied the example site and you don’t want a blog section, or want to link to an external blog instead, just delete the blog subdirectory.

Working with top-level landing pages.

Docsy’s default page template has no left nav and is useful for creating a home page for your site or other “landing” type pages.

Customizing the example site pages

If you’ve copied the example site, you already have a simple site landing page in content/en/_index.html. This is made up of Docsy’s provided Hugo shortcode page blocks.

To customize the large landing image, which is in a cover block, replace the content/en/featured-background.jpg file in your project with your own image (it can be called whatever you like as long as it has background in the file name). You can remove or add as many blocks as you like, as well as adding your own custom content.

The example site also has an About page in content/en/about/_index.html using the same Docsy template. Again, this is made up of page blocks, including another background image in content/en/about/featured-background.jpg. As with the site landing page, you can replace the image, remove or add blocks, or just add your own content.

Building your own landing pages

If you’ve just used the theme, you can still use all Docsy’s provided page blocks (or any other content you want) to build your own landing pages in the same file locations.

Adding a community page

The community landing page template has boilerplate content that’s automatically filled in with the project name and community links specified in config.toml/config.yaml/config.json, providing your users with quick links to resources that help them get involved in your project. The same links are also added by default to your site footer.

• Configuration file:
• config.toml
• config.yaml
• config.json

[params.links]
# End user relevant links. These will show up on left side of footer and in the community page if you have one.
[[params.links.user]]
	name = "User mailing list"
	url = "https://example.org/mail"
	icon = "fa fa-envelope"
        desc = "Discussion and help from your fellow users"
[[params.links.user]]
	name ="Twitter"
	url = "https://example.org/twitter"
	icon = "fab fa-twitter"
        desc = "Follow us on Twitter to get the latest news!"
[[params.links.user]]
	name = "Stack Overflow"
	url = "https://example.org/stack"
	icon = "fab fa-stack-overflow"
        desc = "Practical questions and curated answers"
# Developer relevant links. These will show up on right side of footer and in the community page if you have one.
[[params.links.developer]]
	name = "GitHub"
	url = "https://github.com/google/docsy"
	icon = "fab fa-github"
        desc = "Development takes place here!"
[[params.links.developer]]
	name = "Slack"
	url = "https://example.org/slack"
	icon = "fab fa-slack"
        desc = "Chat with other project developers"
[[params.links.developer]]
	name = "Developer mailing list"
	url = "https://example.org/mail"
	icon = "fa fa-envelope"
        desc = "Discuss development issues around the project"

params:
  links:
    user:
      - name: User mailing list
        url: 'https://example.org/mail'
        icon: fa fa-envelope
        desc: Discussion and help from your fellow users
      - name: Twitter
        url: 'https://example.org/twitter'
        icon: fab fa-twitter
        desc: Follow us on Twitter to get the latest news!
      - name: Stack Overflow
        url: 'https://example.org/stack'
        icon: fab fa-stack-overflow
        desc: Practical questions and curated answers
    developer:
      - name: GitHub
        url: 'https://github.com/google/docsy'
        icon: fab fa-github
        desc: Development takes place here!
      - name: Slack
        url: 'https://example.org/slack'
        icon: fab fa-slack
        desc: Chat with other project developers
      - name: Developer mailing list
        url: 'https://example.org/mail'
        icon: fa fa-envelope
        desc: Discuss development issues around the project

{
  "params": {
    "links": {
      "user": [
        {
          "name": "User mailing list",
          "url": "https://example.org/mail",
          "icon": "fa fa-envelope",
          "desc": "Discussion and help from your fellow users"
        },
        {
          "name": "Twitter",
          "url": "https://example.org/twitter",
          "icon": "fa-brands fa-twitter",
          "desc": "Follow us on Twitter to get the latest news!"
        },
        {
          "name": "Stack Overflow",
          "url": "https://example.org/stack",
          "icon": "fa-brands fa-stack-overflow",
          "desc": "Practical questions and curated answers"
        }
      ],
      "developer": [
        {
          "name": "GitHub",
          "url": "https://github.com/google/docsy",
          "icon": "fa-brands fa-github",
          "desc": "Development takes place here!"
        },
        {
          "name": "Slack",
          "url": "https://example.org/slack",
          "icon": "fa-brands fa-slack",
          "desc": "Chat with other project developers"
        },
        {
          "name": "Developer mailing list",
          "url": "https://example.org/mail",
          "icon": "fa fa-envelope",
          "desc": "Discuss development issues around the project"
        }
      ]
    }
  }
}

If you’re creating your own site and want to add a page using this template, add a /community/_index.md file in your content root directory. If you’ve copied the example site and don’t want a community page, just delete the /content/en/community/ directory in your project repo.

Adding static content

You may want to serve some non-Hugo-built content along with your site: for example, if you have generated reference docs using Doxygen, Javadoc, or other doc generation tools.

To add static content to be served “as-is”, just add the content as a folder and/or files in your site’s static directory. When your site is deployed, content in this directory is served at the site root path. So, for example, if you have added content at /static/reference/cpp/, users can access that content at http://{server-url}/reference/cpp/ and you can link to pages in this directory from other pages at /reference/cpp/{file name}.

You can also use this directory for other files used by your project, including image files. You can find out more about serving static files, including configuring multiple directories for static content, in Static Files.

RSS feeds

Hugo will, by default, create an RSS feed for the home page and any section. For the main RSS feed you can control which sections to include by setting a site param in your config.toml/config.yaml/config.json. This is the default configuration:

• Configuration file:
• config.toml
• config.yaml
• config.json

rss_sections = ["blog"]

rss_sections:
  - blog

{
  "rss_sections": [
    "blog"
  ]
}

To disable all RSS feeds, add the following to your config.toml/config.yaml/config.json:

• Configuration file:
• config.toml
• config.yaml
• config.json

disableKinds = ["RSS"]

disableKinds:
  - RSS

{
  "disableKinds": [
    "RSS"
  ]
}

[outputs]
section = [ "HTML", "RSS", "print" ]

outputs:
  section:
    - HTML
    - RSS
    - print

{
  "outputs": {
    "section": [
      "HTML",
      "RSS",
      "print"
    ]
  }
}

Sitemap

Hugo creates a sitemap.xml file for your generated site by default: for example, here’s the sitemap for this site.

You can configure the frequency with which your sitemap is updated, your sitemap filename, and the default page priority in your config.toml/config.yaml/config.json:

• Configuration file:
• config.toml
• config.yaml
• config.json

[sitemap]
  changefreq = "monthly"
  filename = "sitemap.xml"
  priority = 0.5

sitemap:
  changefreq: monthly
  filename: sitemap.xml
  priority: 0.5

{
  "sitemap": {
    "changefreq": "monthly",
    "filename": "sitemap.xml",
    "priority": 0.5
  }
}

To override any of these values for a given page, specify it in page frontmatter:

• Front matter:
• toml
• yaml
• json

+++
title = "Adding Content"
linkTitle = "Adding Content"
weight = 1
description = '''
Add different types of content to your Docsy site.
'''
[sitemap]
priority = 1
+++

---
title: "Adding Content"
linkTitle: "Adding Content"
weight: 1
description: >
  Add different types of content to your Docsy site.  
sitemap:
  priority: 1.0
---

{
  "title": "Adding Content",
  "linkTitle": "Adding Content",
  "weight": 1,
  "description": "Add different types of content to your Docsy site.\n",
  "sitemap": {
    "priority": 1
  }
}

To learn more about configuring sitemaps, see Sitemap Template.

2 - Look and Feel

By default, a site using Docsy has the theme’s default fonts, colors, and general look and feel. However, if you want your own color scheme (and you probably will!) you can very easily override the theme defaults with your own project-specific values - Hugo will look in your project files first when looking for information to build your site. And because Docsy uses Bootstrap 4 and SCSS for styling, you can override just single values (such as project colors and fonts) in its special SCSS project variables file, or do more serious customization by creating your own styles.

Docsy also provides options for styling your code blocks, using either Chroma or Prism for highlighting.

Project style files

To customize your project’s look and feel, create your own version of either or both of the following Docsy placeholder files (note the _project.scss suffixes):

• assets/scss/_variables_project.scss is where you add project-specific definitions of theme variables such as site colors, as well as any additional Bootstrap variable values you want to set. You can find a list of Docsy’s theme variables and their default values in assets/scss/_variables.scss. For information about other Bootstrap 4 variables, see Variable defaults and Bootstrap’s v4-dev/scss/_variables.scss file.
• assets/scss/_styles_project.scss is where you can add your own custom SCSS styles, including overriding any of the styles in Docsy’s theme SCSS files.

Site colors

To easily customize your site’s colors, add SCSS variable overrides to assets/scss/_variables_project.scss. A simple example changing the primary and secondary color to two shades of purple:

$primary: #390040;
$secondary: #A23B72;

The theme has features such as rounded corners and gradient backgrounds enabled by default. These can also be toggled in your project variables file:

$enable-gradients: true;
$enable-rounded: true;
$enable-shadows: true;

Fonts

The theme uses Open Sans as its primary font. To disable Google Fonts and use a system font, set this SCSS variable in assets/scss/_variables_project.scss:

$td-enable-google-fonts: false;

To configure another Google Font:

$google_font_name: "Open Sans";
$google_font_family: "Open+Sans:300,300i,400,400i,700,700i";

Note that if you decide to go with a font with different weights (in the built-in configuration this is 300 (light), 400 (medium) and 700 (bold)), you also need to adjust the weight related variables, i.e. variables starting with $font-weight-.

CSS utilities

For documentation of available CSS utility classes, see the Bootstrap Documentation. This theme adds very little on its own in this area. However, we have added some color state CSS classes that can be useful in a dynamic context:

• .-bg-<color>
• .-text-<color>

You can use these classes, for example, to style your text in an appropriate color when you don’t know if the primary color is dark or light, to ensure proper color contrast. They are also useful when you receive the color code as a shortcode parameter.

The value of <color> can be any of the color names, primary, white, dark, warning, light, success, 300, blue, orange etc.

When you use .-bg-<color>, the text colors will be adjusted to get proper contrast:

<div class="-bg-primary p-3 display-4">Background: Primary</div>
<div class="-bg-200 p-3 display-4">Background: Gray 200</div>

.-text-<color> sets the text color only:

<div class="-text-blue pt-3 display-4">Text: Blue</div>

Code highlighting with Chroma

With Hugo version 0.60 and higher, you can choose from a range of code block highlight and colour styles using Chroma that are applied to your fenced code blocks by default. If you copied a recent config.toml your site uses Tango (like this site), otherwise the Hugo default is Monokai. You can switch to any of the available Chroma styles (including our Docsy default Tango) using your config.toml/config.yaml/config.json:

• Configuration file:
• config.toml
• config.yaml
• config.json

[markup]
  [markup.goldmark]
    [markup.goldmark.renderer]
      unsafe = true
  [markup.highlight]
      # See a complete list of available styles at https://xyproto.github.io/splash/docs/all.html
      style = "tango"

markup:
  goldmark:
    renderer:
      unsafe: true
  highlight:
    style: tango

{
  "markup": {
    "goldmark": {
      "renderer": {
        "unsafe": true
      }
    },
    "highlight": {
      "style": "tango"
    }
  }
}

By default code highlighting styles are not applied to code blocks without a specified language, instead you get Docsy’s default style of grey with black text. If you would like the code highlighting style to apply to all code blocks, even without a language, uncomment or add the following line under [markup.highlight] in your config.toml/config.yaml/config.json.

• Configuration file:
• config.toml
• config.yaml
• config.json

# Uncomment if you want your chosen highlight style used for code blocks without a specified language
guessSyntax = true

guessSyntax: true

"guessSyntax": true

You can find out more about code highlighting in Hugo with Chroma in Syntax Highlighting.

Code highlighting with Prism

Optionally, you can enable Prism syntax highlighting in your config.toml/config.yaml/config.json:

• Configuration file:
• config.toml
• config.yaml
• config.json

# Enable syntax highlighting and copy buttons on code blocks with Prism
prism_syntax_highlighting = true

prism_syntax_highlighting: true

"prism_syntax_highlighting": true

When this option is enabled your site uses Prism instead of Chroma for code block highlighting.

Prism is a popular open source syntax highlighter which supports over 200 languages and various plugins.

Docsy includes JavaScript and CSS files for a basic Prism configuration, which supports:

• Code blocks styled with the Prism Default theme
• Copy to clipboard buttons on code blocks
• Syntax highlighting for a number of common languages, as specified in the following Prism download link, Customize your download.

Code blocks with no language

By default, Prism code highlighting styles are not applied to code blocks without a specified language, instead you get Docsy’s default style of grey with black text. To apply Prism styling to code blocks with no language or a language not supported by Prism, specify none as the language after your triple backticks.

Extending Prism for additional languages or plugins

If the included Prism configuration is not sufficient for your requirements, and you want to use additional languages or plugins you can replace the included files with your own.

1. Download your own Prism JS and CSS files from https://prismjs.com/download.html
2. Replace the included Prism JS and CSS with the files you downloaded:
   • Copy the Javascript file to static/js/prism.js
   • Copy the CSS file to static/css/prism.css

Navbar

For pages containing a blocks/cover shortcode, like most homepages, the navbar is translucent as long as the hero image hasn’t scrolled up past the navbar. For an example, see the About Docsy page. This initial translucent setting ensures that the hero image is maximally visible.

After the hero image has scrolled past the navbar, the navbar’s (opaque) background color is set – usually to the site’s primary color.

The text of navbar entries can be difficult to read with some hero images. In these cases, you can disable navbar translucency by setting the params.ui.navbar_translucent_over_cover_disable option to true in your site’s configuration file.

Styling your project logo and name

The default Docsy navbar (.td-navbar) displays your site identity, consisting of the following:

1. Your logo, which is included in the navbar as an inline SVG, styled by .td-navbar .navbar-brand svg. For the style details, see _nav.scss.

   To ensure your logo displays correctly, you may want to resize it and ensure that it doesn’t have height and width attributes so that its size is fully responsive. Override the default styling of .td-navbar .navbar-brand svg or (equivalently) .td-navbar .navbar-brand__logo as needed.

2. Your project name, which is the site title. If you don’t want your project name to appear (for example, because your logo is or contains a wordmark), then add the following custom styling to your project’s styles:

   .td-navbar .navbar-brand__name {
     display: none;
   }
   

Customizing templates

Add code to head or before body end

If you need to add some code (CSS import, cookie consent, or similar) to the head section on every page, add the head-end.html partial to your project:

layouts/partials/hooks/head-end.html

And add the code you need in that file. Your partial code is automatically included just before the end of the theme partial head.html. The theme version of head-end.html is empty.

Similarly, if you want to add some code right before the body end, create your own version of the following file:

layouts/partials/hooks/body-end.html

Any code in this file is included automatically at the end of the theme partial scripts.html.

Both head.html and scripts.html are then used to build Docsy’s base page layout, which is used by all the other page templates:

<!doctype html>
<html lang="{{ .Site.Language.Lang }}" class="no-js">
  <head>
    {{ partial "head.html" . }}
  </head>
  <body class="td-{{ .Kind }}">
    <header>
      {{ partial "navbar.html" . }}
    </header>
    <div class="container-fluid td-default td-outer">
      <main role="main" class="td-main">
        {{ block "main" . }}{{ end }}
      </main>
      {{ partial "footer.html" . }}
    </div>
    {{ partialCached "scripts.html" . }}
  </body>
</html>

3 - Navigation and Search

Top-level menu

The top level menu (the one that appears in the top navigation bar for the entire site) uses your site’s main menu. All Hugo sites have a main menu array of menu entries, accessible via the .Site.Menus site variable and populatable via page front matter or your site’s config.toml/config.yaml/config.json.

To add a page or section to this menu, add it to the site’s main menu in either config.toml/config.yaml/config.json or in the destination page’s front matter (in _index.md or _index.html for a section, as that’s the section landing page). For example, here’s how we added the Documentation section landing page to the main menu in this site:

• Front matter:
• toml
• yaml
• json

+++
title = "Welcome to Docsy"
linkTitle = "Documentation"

[menu.main]
weight = 20
pre = "<i class='fa-solid fa-book'></i>"
+++

---
title: "Welcome to Docsy"
linkTitle: "Documentation"
menu:
  main:
    weight: 20
    pre: <i class='fa-solid fa-book'></i>
---

{
  "title": "Welcome to Docsy",
  "linkTitle": "Documentation",
  "menu": {
    "main": {
      "weight": 20,
      "pre": "<i class='fa-solid fa-book'></i>"
    }
  }
}

The menu is ordered from left to right by page weight. So, for example, a section index or page with weight: 30 would appear after the Documentation section in the menu, while one with weight: 10 would appear before it.

If you want to add a link to an external site to this menu, add it in config.toml/config.yaml/config.json, specifying the weight.

• Configuration file:
• config.toml
• config.yaml
• config.json

[[menu.main]]
    name = "GitHub"
    weight = 50
    url = "https://github.com/google/docsy/"

menu:
  main:
    - name: GitHub
      weight: 50
      url: 'https://github.com/google/docsy/'

{
  "menu": {
    "main": [
      {
        "name": "GitHub",
        "weight": 50,
        "url": "https://github.com/google/docsy/"
      }
    ]
  }
}

Adding icons to the top-level menu

As described in the Hugo docs, you can add icons to the top-level menu by using the pre and/or post parameter for main menu items defined in your site’s config.toml/config.yaml/config.json or via page front matter. For example, the following configuration adds the GitHub icon to the GitHub menu item, and a New! alert to indicate that this is a new addition to the menu.

• Configuration file:
• config.toml
• config.yaml
• config.json

[[menu.main]]
    name = "GitHub"
    weight = 50
    url = "https://github.com/google/docsy/"
    pre = "<i class="fa-brands fa-github"></i>"
    post = "<span class='alert'>New!</span>"

menu:
  main:
    - name: GitHub
      weight: 50
      url: 'https://github.com/google/docsy/'
      pre: <i class="fa-brands fa-github"></i>
      post: <span class='alert'>New!</span>

{
  "menu": {
    "main": [
      {
        "name": "GitHub",
        "weight": 50,
        "url": "https://github.com/google/docsy/",
        "pre": "<i class="fa-brands fa-github"></i>",
        "post": "<span class='alert'>New!</span>"
      }
    ]
  }
}

You can find a complete list of icons to use in the FontAwesome documentation. Docsy includes the free FontAwesome icons by default.

Adding a version drop-down

If you add some [params.versions] in config.toml, the Docsy theme adds a version selector drop down to the top-level menu.

You can find out more in the guide to versioning your docs.

Adding a language drop-down

If you configure more than one language in config.toml, the Docsy theme adds a language selector drop down to the top-level menu. Selecting a language takes the user to the translated version of the current page, or the home page for the given language.

You can find out more in Multi-language support.

Section menu

The section menu, as shown in the left side of the docs section, is automatically built from the content tree. Like the top-level menu, it is ordered by page or section index weight (or by page creation date if weight is not set), with the page or index’s Title, or linkTitle if different, as its link title in the menu. If a section subfolder has pages other than _index.md or _index.html, those pages will appear as a submenu, again ordered by weight. For example, here’s the metadata for this page showing its weight and title:

• Front matter:
• toml
• yaml
• json

+++
title = "Navigation and Search"
linkTitle = "Navigation and Search"
date = 2017-01-05T00:00:00.000Z
weight = 3
description = '''
Customize site navigation and search for your Docsy site.
'''
+++

---
title: "Navigation and Search"
linkTitle: "Navigation and Search"
date: 2017-01-05
weight: 3
description: >
  Customize site navigation and search for your Docsy site.  
---

{
  "title": "Navigation and Search",
  "linkTitle": "Navigation and Search",
  "date": "2017-01-05T00:00:00.000Z",
  "weight": 3,
  "description": "Customize site navigation and search for your Docsy site.\n"
}

To hide a page or section from the left navigation menu, set toc_hide: true in the front matter.

To hide a page from the section summary on a docs section landing page, set hide_summary: true in the front matter. If you want to hide a page from both the TOC menu and the section summary list, you need to set both toc_hide and hide_summary to true in the front matter.

• Front matter:
• toml
• yaml
• json

+++
title = "My Hidden Page"
weight = 99
toc_hide = true
hide_summary = true
description = '''
Page hidden from both the TOC menu and the section summary list.
'''
+++

---
title: "My Hidden Page"
weight: 99
toc_hide: true
hide_summary: true
description: >
  Page hidden from both the TOC menu and the section summary list.  
---

{
  "title": "My Hidden Page",
  "weight": 99,
  "toc_hide": true,
  "hide_summary": true,
  "description": "Page hidden from both the TOC menu and the section summary list.\n"
}

Section menu options

By default, the section menu shows the current section fully expanded all the way down. This may make the left nav too long and difficult to scan for bigger sites. Try setting site parameter ui.sidebar_menu_compact = true in config.toml.

With the compact menu (.ui.sidebar_menu_compact = true), only the current page’s ancestors, siblings and direct descendants are shown. You can use the optional parameter .ui.ul_show to set a desired menu depth to always be visible. For example, with .ui.ul_show = 1 the first menu level is always displayed.

As well as the completely expanded and compact menu options, you can also create a foldable menu by setting the site parameter ui.sidebar_menu_foldable = true in config.toml. The foldable menu lets users expand and collapse menu sections by toggling arrow icons beside the section parents in the menu.

On large sites (default: > 2000 pages) the section menu is not generated for each page, but cached for the whole section. The HTML classes for marking the active menu item (and menu path) are then set using JS. You can adjust the limit for activating the cached section menu with the optional parameter .ui.sidebar_cache_limit.

Add icons to the section menu

You can add icons to the section menu in the sidebar by setting the icon parameter in the page front matter (e.g. icon: fa-solid fa-screwdriver-wrench).

You can find a complete list of icons to use in the FontAwesome documentation. Docsy includes the free FontAwesome icons by default.

Out of the box, if you want to use icons, you should define icons for all items on the same menu level in order to ensure an appropriate look. If the icons are used in a different way, individual CSS adjustments are likely necessary.

Add manual links to the section menu

By default the section menu is entirely generated from your section’s pages. If you want to add a manual link to this menu, such as a link to an external site or a page in a different section of your site, you can do this by creating a placeholder page file in the doc hierarchy with the appropriate weight and some special parameters in its metadata (frontmatter) to specify the link details.

To create a placeholder page, create a page file as usual in the directory where you want the link to show up in the menu, and add a manualLink parameter to its metadata. If a page has manualLink in its metadata, Docsy generates a link for it in the section menu for this page and in the section index (the list of the child pages of a section on a landing page - see description in the Docsy docs), but the link destination is replaced by the value of manualLink. The link text is the title (or linkTitle if set) of your placeholder page. You can optionally also set the title attribute of the link with the parameter manualLinkTitle and a link target with manualLinkTarget - for example if you want an external link to open in a new tab you can set the link target to _blank. Docsy automatically adds rel=noopener to links that open new tabs as a security best practice.

You can also use manualLink to add an additional cross reference to another existing page of your site. For internal links you can choose to use the parameter manualLinkRelref instead of manualLink to use the built-in Hugo function relref. If relref can’t find a unique page in your site, Hugo throws a error message.

Breadcrumb navigation

Breadcrumb navigation links appear at the top of each page by default. To disable breadcrumb navigation, set site param ui.breadcrumb_disable = true in config.toml.

Breadcrumb navigation links are also shown for each item on the taxonomy results page (i.e. when you click one of the taxonomy labels, e.g. Tags/Categories). These breadcrumbs can be disabled in config.toml by setting site param taxonomy_breadcrumb_disable = true.

Site search options

Docsy offers multiple options that let your readers search your site content, so you can pick one that suits your needs. You can choose from:

• Google Custom Search Engine (GCSE), the default option, which uses Google’s index of your public site to generate a search results page.
• Algolia DocSearch, which uses Algolia’s indexing and search mechanism, and provides an organized dropdown of search results when your readers use the search box. Algolia DocSearch is free for public documentation sites.
• Local search with Lunr, which uses Javascript to index and search your site without the need to connect to external services. This option doesn’t require your site to be public.

If you enable any of these search options in your config.toml, a search box displays in the right of your top navigation bar. By default a search box also displays at the top of the section menu in the left navigation pane, which you can disable if you prefer, or if you’re using a search option that only works with the top search box.

Be aware that if you accidentally enable more than one search option in your config.toml you may get unexpected results (for example, if you have added the .js for Algolia DocSearch, you’ll get Algolia results if you enable GCSE search but forget to disable Algolia search).

Disabling the sidebar search box

By default, the search box appears in both the top navigation bar and at the top of the sidebar left navigation pane. If you don’t want the sidebar search box, set sidebar_search_disable to true in config.toml/config.yaml/config.json:

• Configuration file:
• config.toml
• config.yaml
• config.json

sidebar_search_disable = true

sidebar_search_disable: true

"sidebar_search_disable": true

Configure search with a Google Custom Search Engine

By default Docsy uses a Google Custom Search Engine (GCSE) to search your site. To enable this feature, you’ll first need to make sure that you have built and deployed a production version of your site, as otherwise your site won’t be crawled and indexed.

Setting up site search

1. Create a Google Custom Search Engine for your deployed site by clicking New search engine on the Custom Search page and following the instructions. Make a note of the ID for your new search engine.

2. Add any further configuration you want to your search engine using the Edit search engine options. In particular you may want to do the following:

   • Select Look and feel. Change from the default Overlay layout to Results only, as this option means your search results are embedded in your search page rather than appearing in a separate box. Click Save to save your changes.
   • Edit the default result link behavior so that search results from your site don’t open in a new tab. To do this, select Search Features - Advanced - Websearch Settings. In the Link Target field, type “_parent”. Click Save to save your changes.

Adding the search page

Once you have your search engine set up, you can add the feature to your site:

1. Ensure you have a Markdown file in content/en/search.md (and one per other languages if needed) to display your search results. It only needs a title and layout: search, as in the following example:

   • Front matter:
   • toml
   • yaml
   • json

   +++
   title = "Search Results"
   layout = "search"
   +++

   ---
   title: Search Results
   layout: search
   ---

   {
       "title": "Search Results",
       "layout": "search"
   }

2. Add your Google Custom Search Engine ID to the site params in config.toml/config.yaml/config.json. You can add different values per language if needed.

   • Configuration file:
   • config.toml
   • config.yaml
   • config.json

   gcs_engine_id = "011737558837375720776:fsdu1nryfng"

   gcs_engine_id: '011737558837375720776:fsdu1nryfng'

   {
     "gcs_engine_id": "011737558837375720776:fsdu1nryfng"
   }

Disabling GCSE search

If you don’t specify a Google Custom Search Engine ID for your project and haven’t enabled any other search options, the search box won’t appear in your site. If you’re using the default config.toml from the example site and want to disable search, just comment out or remove the relevant line.

Configure Algolia DocSearch

As an alternative to GCSE, you can use Algolia DocSearch with this theme. Algolia DocSearch is free for public documentation sites. Docsy supports Algolia DocSearch v3.

Sign up for Algolia DocSearch

Complete the form at https://docsearch.algolia.com/apply/.

If you are accepted to the program, you will receive the code to add to your documentation site from Algolia by email.

Adding Algolia DocSearch

1. Enable Algolia DocSearch in config.toml/config.yaml/config.json.

   • Configuration file:
   • config.toml
   • config.yaml
   • config.json

   algolia_docsearch = true

   algolia_docsearch: true

   {
     "algolia_docsearch": true
   }

2. Remove or comment out any GCSE ID in config.toml/config.yaml/config.json and ensure local search is set to false as you can only have one type of search enabled. See Disabling GCSE search.

3. Disable the sidebar search in config.toml/config.yaml/config.json as this is not currently supported for Algolia DocSearch. See Disabling the sidebar search box.

4. Add the CSS and JS to use Algolia to the head and body of every page in your site, following the instructions in Add code to head or before body end.

   • In head-end.html add the DocSearch CSS:

     <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@docsearch/css@3" />
     

   • In body-end.html add the DocSearch script, replacing the docsearch details with the snippet you get from Algolia (the example below is Algolia’s own site index!). You must provide #docsearch as your container value as that’s the ID of the div we provide in Docsy’s layout:

     <script src="https://cdn.jsdelivr.net/npm/@docsearch/js@3"></script>
     <script type="text/javascript">docsearch({
       container: '#docsearch',
       appId: 'R2IYF7ETH7',
       apiKey: '599cec31baffa4868cae4e79f180729b',
       indexName: 'docsearch',
       });</script>
     

You can find out more about how to configure DocSearch in the Algolia DocSearch V3 Getting started guide.

When you’ve completed these steps, Algolia search should be enabled on your site. Search results are displayed as a pop-up, so you don’t need to add any search results page.

Configure local search with Lunr

Lunr is a Javascript-based search option that lets you index your site and make it searchable without the need for external, server-side search services. This is a good option particularly for smaller or non-public sites.

To add Lunr search to your Docsy site:

1. Enable local search in config.toml/config.yaml/config.json.

   • Configuration file:
   • config.toml
   • config.yaml
   • config.json

   offlineSearch = true

   offlineSearch: true

   {
     "offlineSearch": true
   }

2. Remove or comment out any GCSE ID in config.toml/config.yaml/config.json and ensure Algolia DocSearch is set to false, as you can only have one type of search enabled. See Disabling GCSE search.

Once you’ve completed these steps, local search is enabled for your site and results appear in a drop down when you use the search box.

Changing the summary length of the local search results

You can customize the summary length by setting offlineSearchSummaryLength in config.toml/config.yaml/config.json.

• Configuration file:
• config.toml
• config.yaml
• config.json

#Enable offline search with Lunr.js
offlineSearch = true
offlineSearchSummaryLength = 200

offlineSearch: true
offlineSearchSummaryLength: 200

{
  "offlineSearch": true,
  "offlineSearchSummaryLength": 200
}

Changing the maximum result count of the local search

You can customize the maximum result count by setting offlineSearchMaxResults in config.toml/config.yaml/config.json.

• Configuration file:
• config.toml
• config.yaml
• config.json

offlineSearch = true
offlineSearchMaxResults = 25

offlineSearch: true
offlineSearchMaxResults: 25

{
  "offlineSearch": true,
  "offlineSearchMaxResults": 25
}

Changing the width of the local search results popover

The width of the search results popover will automatically widen according to the content.

If you want to limit the width, add the following scss into assets/scss/_variables_project.scss.

.td-offline-search-results {
  max-width: 460px;
}

Excluding pages from local search results

To exclude pages from local search results, add exclude_search: true to the the frontmatter of each page:

• Front matter:
• toml
• yaml
• json

+++
title = "Index"
weight = 10
exclude_search = true
+++

---
title: "Index"
weight: 10
exclude_search: true
---

{
  "title": "Index",
  "weight": 10,
  "exclude_search": true
}

4 - Doc Versioning

Depending on your project’s releases and versioning, you may want to let your users access previous versions of your documentation. How you deploy the previous versions is up to you. This page describes the Docsy features that you can use to provide navigation between the various versions of your docs and to display an information banner on the archived sites.

Adding a version drop-down menu

If you add some [params.versions] in config.toml/config.yaml/config.json, the Docsy theme adds a version selector drop down to the top-level menu. You specify a URL and a name for each version you would like to add to the menu, as in the following example:

• Configuration file:
• config.toml
• config.yaml
• config.json

# Add your release versions here
[[params.versions]]
  version = "master"
  url = "https://master.kubeflow.org"

[[params.versions]]
  version = "v0.2"
  url = "https://v0-2.kubeflow.org"

[[params.versions]]
  version = "v0.3"
  url = "https://v0-3.kubeflow.org"

params:
  versions:
    - version: master
      url: 'https://master.kubeflow.org'
    - version: v0.2
      url: 'https://v0-2.kubeflow.org'
    - version: v0.3
      url: 'https://v0-3.kubeflow.org'

{
  "params": {
    "versions": [
      {
        "version": "master",
        "url": "https://master.kubeflow.org"
      },
      {
        "version": "v0.2",
        "url": "https://v0-2.kubeflow.org"
      },
      {
        "version": "v0.3",
        "url": "https://v0-3.kubeflow.org"
      }
    ]
  }
}

Remember to add your current version so that users can navigate back!

The default title for the version drop-down menu is Releases. To change the title, change the version_menu parameter in config.toml/config.yaml/config.json:

• Configuration file:
• config.toml
• config.yaml
• config.json

version_menu = "Releases"

version_menu: 'Releases'

"version_menu": "Releases"

If you set the version_menu_pagelinks parameter to true, then links in the version drop-down menu point to the current page in the other version, instead of the main page. This can be useful if the document doesn’t change much between the different versions. Note that if the current page doesn’t exist in the other version, the link will be broken.

You can read more about Docsy menus in the guide to navigation and search.

Displaying a banner on archived doc sites

If you create archived snapshots for older versions of your docs, you can add a note at the top of every page in the archived docs to let readers know that they’re seeing an unmaintained snapshot and give them a link to the latest version.

For example, see the archived docs for Kubeflow v0.6:

To add the banner to your doc site, make the following changes in your config.toml/config.yaml/config.json file:

1. Set the archived_version parameter to true:

   • Configuration file:
   • config.toml
   • config.yaml
   • config.json

   archived_version = true

   archived_version: true

   "archived_version": true

2. Set the version parameter to the version of the archived doc set. For example, if the archived docs are for version 0.1:

   • Configuration file:
   • config.toml
   • config.yaml
   • config.json

   version = "0.1"

   version: '0.1'

   "version": "0.1"

3. Make sure that url_latest_version contains the URL of the website that you want to point readers to. In most cases, this should be the URL of the latest version of your docs:

   • Configuration file:
   • config.toml
   • config.yaml
   • config.json

   url_latest_version = "https://your-latest-doc-site.com"

   url_latest_version: 'https://your-latest-doc-site.com'

   "url_latest_version": "https://your-latest-doc-site.com"

5 - Docsy Shortcodes

Rather than writing all your site pages from scratch, Hugo lets you define and use shortcodes. These are reusable snippets of content that you can include in your pages, often using HTML to create effects that are difficult or impossible to do in simple Markdown. Shortcodes can also have parameters that let you, for example, add your own text to a fancy shortcode text box. As well as Hugo’s built-in shortcodes, Docsy provides some shortcodes of its own to help you build your pages.

Shortcode blocks

The theme comes with a set of custom Page Block shortcodes that can be used to compose landing pages, about pages, and similar.

These blocks share some common parameters:

height

A pre-defined height of the block container. One of min, med, max, full, or auto. Setting it to full will fill the Viewport Height, which can be useful for landing pages.

color

The block will be assigned a color from the theme palette if not provided, but you can set your own if needed. You can use all of Bootstrap’s color names, theme color names or a grayscale shade. Some examples would be primary, white, dark, warning, light, success, 300, blue, orange. This will become the background color of the block, but text colors will adapt to get proper contrast.

blocks/cover

The blocks/cover shortcode creates a landing page type of block that fills the top of the page.

{{< blocks/cover title="Welcome!" image_anchor="center" height="full" color="primary" >}}
<div class="mx-auto">
	<a class="btn btn-lg btn-primary mr-3 mb-4" href="{{< relref "/docs" >}}">
		Learn More <i class="fa-solid fa-circle-right ml-2"></i>
	</a>
	<a class="btn btn-lg btn-secondary mr-3 mb-4" href="https://example.org">
		Download <i class="fa-brands fa-github ml-2 "></i>
	</a>
	<p class="lead mt-5">This program is now available in <a href="#">AppStore!</a></p>
	<div class="mx-auto mt-5">
		{{< blocks/link-down color="info" >}}
	</div>
</div>
{{< /blocks/cover >}}

Note that the relevant shortcode parameters above will have sensible defaults, but is included here for completeness.

To set the background image, place an image with the word “background” in the name in the page’s Page Bundle. For example, in our the example site the background image in the home page’s cover block is featured-background.jpg, in the same directory.

For available icons, see Font Awesome.

blocks/lead

The blocks/lead block shortcode is a simple lead/title block with centred text and an arrow down pointing to the next section.

{{% blocks/lead color="dark" %}}
TechOS is the OS of the future.

Runs on **bare metal** in the **cloud**!
{{% /blocks/lead %}}

blocks/section

The blocks/section shortcode is meant as a general-purpose content container. It comes in two “flavors”, one for general content and one with styling more suitable for wrapping a horizontal row of feature sections.

The example below shows a section wrapping 3 feature sections.

{{< blocks/section color="dark" >}}
{{% blocks/feature icon="fa-lightbulb" title="Fastest OS **on the planet**!" %}}
The new **TechOS** operating system is an open source project. It is a new project, but with grand ambitions.
Please follow this space for updates!
{{% /blocks/feature %}}
{{% blocks/feature icon="fa-brands fa-github" title="Contributions welcome!" url="https://github.com/gohugoio/hugo" %}}
We do a [Pull Request](https://github.com/gohugoio/hugo/pulls) contributions workflow on **GitHub**. New users are always welcome!
{{% /blocks/feature %}}
{{% blocks/feature icon="fa-brands fa-twitter" title="Follow us on Twitter!" url="https://twitter.com/GoHugoIO" %}}
For announcement of latest features etc.
{{% /blocks/feature %}}
{{< /blocks/section >}}

blocks/feature

{{% blocks/feature icon="fa-brands fa-github" title="Contributions welcome!" url="https://github.com/gohugoio/hugo" %}}
We do a [Pull Request](https://github.com/gohugoio/hugo/pulls) contributions workflow on **GitHub**. New users are always welcome!
{{% /blocks/feature %}}

blocks/link-down

The blocks/link-down shortcode creates a navigation link down to the next section. It’s meant to be used in combination with the other blocks shortcodes.

<div class="mx-auto mt-5">
	{{< blocks/link-down color="info" >}}
</div>

Shortcode helpers

alert

The alert shortcode creates an alert block that can be used to display notices or warnings.

{{% alert title="Warning" color="warning" %}}
This is a warning.
{{% /alert %}}

Renders to:

pageinfo

The pageinfo shortcode creates a text box that you can use to add banner information for a page: for example, letting users know that the page contains placeholder content, that the content is deprecated, or that it documents a beta feature.

{{% pageinfo color="primary" %}}
This is placeholder content.
{{% /pageinfo %}}

Renders to:

imgproc

The imgproc shortcode finds an image in the current Page Bundle and scales it given a set of processing instructions.

{{< imgproc spruce Fill "400x450" >}}
Norway Spruce Picea abies shoot with foliage buds.
{{< /imgproc >}}

The example above has also a byline with photo attribution added. When using illustrations with a free license from WikiMedia and similar, you will in most situations need a way to attribute the author or licensor. You can add metadata to your page resources in the page front matter. The byline param is used by convention in this theme:

• Front matter:
• toml
• yaml
• json

+++
[[resources]]
src = "**spruce*.jpg"

  [resources.params]
  byline = "Photo: Bjørn Erik Pedersen / CC-BY-SA"
+++

---
resources:
- src: "**spruce*.jpg"
  params:
    byline: "Photo: Bjørn Erik Pedersen / CC-BY-SA"
---

{
  "resources": [
    {
      "src": "**spruce*.jpg",
      "params": {
        "byline": "Photo: Bjørn Erik Pedersen / CC-BY-SA"
      }
    }
  ]
}

swaggerui

The swaggerui shortcode can be placed anywhere inside a page with the swagger layout; it renders Swagger UI using any OpenAPI YAML or JSON file as source. This file can be hosted anywhere you like, for example in your site’s root /static folder.

• Front matter:
• toml
• yaml
• json

+++
title = "Pet Store API"
type = "swagger"
weight = 1
description = "Reference for the Pet Store API"
+++

{{< swaggerui src="/openapi/petstore.yaml" >}}

---
title: "Pet Store API"
type: swagger
weight: 1
description: Reference for the Pet Store API
---

{{< swaggerui src="/openapi/petstore.yaml" >}}

{
  "title": "Pet Store API",
  "type": "swagger",
  "weight": 1,
  "description": "Reference for the Pet Store API"
}

{{< swaggerui src="/openapi/petstore.yaml" >}}

You can customize Swagger UI’s look and feel by overriding Swagger’s CSS or by editing and compiling a Swagger UI dist yourself and replace themes/docsy/static/css/swagger-ui.css.

redoc

The redoc shortcode uses the open-source Redoc tool to render reference API documentation from an OpenAPI YAML or JSON file. This can be hosted anywhere you like, for example in your site’s root /static folder, but you can use a URL as well, for example:

---
title: "Pet Store API"
type: docs
weight: 1
description: Reference for the Pet Store API
---

{{< redoc "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v2.0/yaml/petstore.yaml" >}}

iframe

With this shortcode you can embed external content into a Docsy page as an inline frame (iframe) - see: https://www.w3schools.com/tags/tag_iframe.asp

Tabbed panes

Sometimes it’s very useful to have tabbed panes when authoring content. One common use-case is to show multiple syntax highlighted code blocks that showcase the same problem, and how to solve it in different programming languages. As an example, the tabbed pane below shows the language-specific variants of the famous Hello world! program one usually writes first when learning a new programming language:

• C
• C++
• Go
• Java
• Kotlin
• Lua
• PHP
• Python
• Ruby
• Scala
• Reference

#include <stdio.h>
#include <stdlib.h>

int main(void)
{
  puts("Hello World!");
  return EXIT_SUCCESS;
}

#include <iostream>

int main()
{
  std::cout << "Hello World!" << std::endl;
}

package main
import "fmt"
func main() {
  fmt.Printf("Hello World!\n")
}

class HelloWorld {
  static public void main( String args[] ) {
    System.out.println( "Hello World!" );
  }
}

fun main(args : Array<String>) {
    println("Hello, world!")
}

print "Hello world"

<?php
echo 'Hello World!';
?>

print("Hello World!")

puts "Hello World!"

object HelloWorld extends App {
  println("Hello world!")
}

The Docsy template provides two shortcodes tabpane and tab that let you easily create tabbed panes. To see how to use them, have a look at the following code block, which renders to a right aligned pane with one disabled and three active tabs:

{{< tabpane text=true right=true >}}
  {{% tab header="**Languages**:" disabled=true /%}}
  {{% tab header="English" lang="en" %}}
  ![Flag United Kingdom](flags/uk.png)
  Welcome!
  {{% /tab %}}
  {{< tab header="German" lang="de" >}}
    <b>Herzlich willkommen!</b>
    <img src="flags/de.png" alt="Flag Germany" style="float: right; padding: 0 0 0 0px">
  {{< /tab >}}
  {{% tab header="Swahili" lang="sw" %}}
  ![Flag Tanzania](flags/tz.png)
  **Karibu sana!**
  {{% /tab %}}
{{< /tabpane >}}

This code translates to the right aligned tabbed pane below, showing a Welcome! greeting in English, German or Swahili:

• Languages:
• English
• German
• Swahili

Welcome!

Herzlich willkommen!

Karibu sana!

Shortcode details

Tabbed panes are implemented using two shortcodes:

• The tabpane shortcode, which is the container element for the tabs. This shortcode can hold the optional named parameters lang, highlight and right. The value of the optional parameters lang and highlight are passed on as second LANG and third OPTIONS arguments to Hugo’s built-in highlight function which is used to render the code blocks of the individual tabs. Specify right=true if you want to right align your tabs. In case the header text of the tab equals the language used in the tab’s code block (as in the first tabbed pane example above), you may specify langEqualsHeader=true in the surrounding tabpane shortcode. Then, the header text of the individual tab is automatically set as lang parameter of the respective tab.
• The various tab shortcodes represent the tabs you would like to show. Specify the named parameter header for each tab in order to set the header text of the tab. If the header parameter is the only parameter inside your tab shortcode, you can specify the header as unnamed parameter, something like { tab "My header" }} … {{ /tab }}. If your tab shortcode does not have any parameters, the header of the tab will default to Tab n. To split the panes into a left aligned and a right aligned tab group, specify right=true in the dividing tab. By giving right=true several times, you can even render multiple tab groups. You can disable a tab by specifying the parameter disabled=true. For enabled tabs, there are two modes for content display, code representation and textual representation:
  • By default, the tab’s content is rendered as code block. In order to get proper syntax highlighting, specify the named parameter lang –and optionally the parameter highlight– for each tab. Parameters set in the parent tabpane shortcode will be overwritten.
  • If the contents of your tabs should be rendered as text with different styles and with optional images, specify text=true as parameter of your tabpane (or your tab). If your content is markdown, use the percent sign % as outermost delimiter of your tab shortcode, your markup should look like {{% tab %}}Your **markdown** content{{% /tab %}}. In case of HTML content, use square brackets <> as outermost delimiters: {{< tab >}}Your <b>HTML</b> content{{< /tab >}}.

Card panes

When authoring content, it’s sometimes very useful to put similar text blocks or code fragments on card like elements, which can be optionally presented side by side. Let’s showcase this feature with the following sample card group which shows the first four Presidents of the United States:

George Washington

*1732     †1799

President: 1789 – 1797

John Adams

* 1735     † 1826

President: 1797 – 1801

Thomas Jefferson

* 1743     † 1826

President: 1801 – 1809

James Madison

* 1751     † 1836

President: 1809 – 1817

Docsy supports creating such card panes via different shortcodes:

• The cardpane shortcode which is the container element for the various cards to be presented.
• The card shortcodes, with each shortcode representing an individual card. While cards are often presented inside a card group, a single card may stand on its own, too. A card shortcode can hold text, images or any other arbitrary kind of markdown or HTML markup as content. If your content is programming code, you are advised to make use of the card-code shortcode, a special kind of card with code-highlighting and other optional features like line numbers, highlighting of certain lines, ….

Shortcode card (for text, images, …)

As stated above, a card is coded using one of the shortcode card or card-code. If your content is any kind of text other than programming code, use the universal cardshortcode. The following code sample demonstrates how to code a card element:

{{< card header="**Imagine**" title="Artist and songwriter: John Lennon" subtitle="Co-writer: Yoko Ono"
          footer="![SignatureJohnLennon](https://server.tld/…/signature.png 'Signature John Lennon')">}}
Imagine there's no heaven, It's easy if you try<br/>
No hell below us, above us only sky<br/>
Imagine all the people living for today…

…
{{< /card >}}

This code translates to the left card shown below, showing the lyrics of John Lennon’s famous song Imagine. A second explanatory card element to the right indicates and explains the individual components of a card:

Imagine

Artist and songwriter: John Lennon

Co-writer: Yoko Ono

Imagine there’s no heaven, It’s easy if you try
No hell below us, above us only sky
Imagine all the people living for today…

Imagine there’s no countries, it isn’t hard to do
Nothing to kill or die for, and no religion too
Imagine all the people living life in peace…

Imagine no possessions, I wonder if you can
No need for greed or hunger - a brotherhood of man
Imagine all the people sharing all the world…

You may say I’m a dreamer, but I’m not the only one
I hope someday you’ll join us and the world will live as one

Header: specified via named parameter Header

Card title: specified via named parameter title

Card subtitle: specified via named parameter subtitle

Content: inner content of the shortcode, this may be formatted text, images, videos, … . If the extension of your page file equals .md, markdown format is expected, otherwise, your content will be treated as plain HTML.

Footer: specified via named parameter footer

While the main content of the card is taken from the inner markup of the card shortcode, the optional elements footer, header, title, and subtitle are all specified as named parameters of the shortcode.

Shortcode card-code (for programming code)

In case you want to display programming code on your card, a special shortcode card-code is provided for this purpose. The following sample demonstrates how to code a card element with the famous Hello world!application coded in C:

{{< card-code header="**C**" lang="C" >}}
#include <stdio.h>
#include <stdlib.h>

int main(void)
{
  puts("Hello World!");
  return EXIT_SUCCESS;
}
{{< /card-code >}}

This code translates to the card shown below:

#include <stdio.h>
#include <stdlib.h>

int main(void)
{
  puts("Hello World!");
  return EXIT_SUCCESS;
}

The card-code shortcode can optionally hold the named parameters lang and/or highlight. The values of these optional parameters are passed on as second LANG and third OPTIONS arguments to Hugo’s built-in highlight function which is used to render the code block presented on the card.

Card groups

Displaying two ore more cards side by side can be easily achieved by putting them between the opening and closing elements of a cardpane shortcode. The general markup of a card group resembles closely the markup of a tabbed pane:

{{< cardpane >}}
  {{< card header="Header card 1" >}}
    Content card 1
  {{< /card >}}
  {{< card header="Header card 2" >}}
    Content card 2
  {{< /card >}}
  {{< card header="Header card 3" >}}
    Content card 3
  {{< /card >}}
{{< /cardpane >}}

Contrary to tabs, cards are presented side by side, however. This is especially useful it you want to compare different programming techniques (traditional vs. modern) on two cards, like demonstrated in the example above:

File[] hiddenFiles = new File("directory_name")
  .listFiles(new FileFilter() {
    public boolean accept(File file) {
      return file.isHidden();
    }
  });

File[] hiddenFiles = new File("directory_name")
  .listFiles(File::isHidden);

Include external files

Sometimes there’s content that is relevant for several documents, or that is maintained in a file that is not necessarily a document. For situations like these, the readfile shortcode allows you to import the contents of an external file into a document.

Reuse documentation

In case you want to reuse some content in several documents, you can write said content in a separate file and include it wherever you need it.

For example, suppose you have a file called installation.md with the following contents:

## Installation

{{% alert title="Note" color="primary" %}}
Check system compatibility before proceeding.
{{% /alert %}}

1.  Download the installation files.

1.  Run the installation script

    `sudo sh install.sh`

1.  Test that your installation was successfully completed.

You can import this section into another document:

The following section explains how to install the database:

{{% readfile "installation.md" %}}

This is rendered as if the instructions were in the parent document. Hugo v0.101.0+ is required for imported files containing shortcodes to be rendered correctly.

The following section explains how to install the database:

Installation

Check system compatibility before proceeding.

1. Download the installation files.

2. Run the installation script

   sudo sh install.sh

3. Test that your installation was successfully completed.

The parameter is the relative path to the file. Only relative paths under the parent file’s working directory are supported.

For files outside the current working directory you can use an absolute path starting with /. The root directory is the /content folder.

Include code files

Suppose you have an includes folder containing several code samples you want to use as part of your documentation. You can use readfile with some additional parameters:

To create a new pipeline, follow the next steps:

1.  Create a configuration file `config.yaml`:

    {{< readfile file="includes/config.yaml" code="true" lang="yaml" >}}

1.  Apply the file to your cluster `kubectl apply config.yaml`

This code automatically reads the content of import/config.yaml and inserts it into the document. The rendered text looks like this:

To create a new pipeline, follow the next steps:

1. Create a configuration file config.yaml:

   apiVersion: tekton.dev/v1beta1
       kind: Task
       metadata:
         name: hello
       spec:
         steps:
           - name: echo
             image: alpine
             script: |
               #!/bin/sh
               echo "Hello World"          
       

2. Apply the file to your cluster kubectl apply config.yaml

The “file” parameter is the relative path to the file. Only relative paths under the parent file’s working directory are supported.

For files outside the current working directory you can use an absolute path starting with /. The root directory is the /content folder.

Conditional text

The conditional-text shortcode allows you to show or hide parts of your content depending on the value of the buildCondition parameter set in your configuration file. This can be useful if you are generating different builds from the same source, for example, using a different product name. This shortcode helps you handle the minor differences between these builds.

{{% conditional-text include-if="foo" %}}
This text appears in the output only if `buildCondition = "foo" is set in your config file`.
{{% /conditional-text %}}
{{% conditional-text exclude-if="bar" %}}
This text does not appear in the output if `buildCondition = "bar" is set in your config file`.
{{% /conditional-text %}}

If you are using this shortcode, note that when evaluating the conditions, substring matches are matches as well. That means, if you set include-if="foobar", and buildcondition = "foo", you have a match!

6 - Logos and Images

Add your logo

By default, Docsy shows a site logo at the start of the navbar, that is, at the extreme left. Place your project’s SVG logo in assets/icons/logo.svg. This overrides the default Docsy logo in the theme.

If you don’t want a logo to appear in the navbar, then set navbar_logo to false in your project’s config:

• Configuration file:
• config.toml
• config.yaml
• config.json

navbar_logo = false

navbar_logo: false

{
  "navbar_logo": false
}

For information about styling your logo, see Styling your project logo and name.

Use icons

Docsy includes the free FontAwesome icons by default, including logos for sites like GitHub and Stack Overflow. You can view all available icons in the FontAwesome documentation, including the FontAwesome version when the icon was added and whether it is available for free tier users. Check Docsy’s package.json and release notes for Docsy’s currently included version of FontAwesome.

You can add FontAwesome icons to your top-level menu, section menu, or anywhere in your text.

Add your favicons

The easiest way to do this is to create a set of favicons via http://cthedot.de/icongen (which lets you create a huge range of icon sizes and options from a single image) and/or https://favicon.io, and put them in your site project’s static/favicons directory. This will override the default favicons from the theme.

Note that https://favicon.io doesn’t create as wide a range of sizes as Icongen but does let you quickly create favicons from text: if you want to create text favicons you can use this site to generate them, then use Icongen to create more sizes (if necessary) from your generated .png file.

If you have special favicon requirements, you can create your own layouts/partials/favicons.html with your links.

Add images

Landing pages

Docsy’s blocks/cover shortcode make it easy to add large cover images to your landing pages. The shortcode looks for an image with the word “background” in the name inside the landing page’s Page Bundle - so, for example, if you’ve copied the example site, the landing page image in content/en/_index.html is content/en/featured-background.jpg.

You specify the preferred display height of a cover block container (and hence its image) using the block’s height parameter. For a full viewport height, use full:

{{< blocks/cover title="Welcome to the Docsy Example Project!" image_anchor="top" height="full" color="orange" >}}
...
{{< /blocks/cover >}}

For a shorter image, as in the example site’s About page, use one of min, med, max or auto (the actual height of the image):

{{< blocks/cover title="About the Docsy Example" image_anchor="bottom" height="min" >}}
...
{{< /blocks/cover >}}

Other pages

To add inline images to other pages, use the imgproc shortcode. Alternatively, if you prefer, just use regular Markdown or HTML images and add your image files to your project’s static directory. You can find out more about using this directory in Adding static content.

Images used on this site

Images used as background images in this site are in the public domain and can be used freely. The porridge image in the example site is by iha31 from Pixabay.

7 - Print Support

Individual documentation pages print well from most browsers as the layouts have been styled to omit navigational chrome from the printed output.

On some sites, it can be useful to enable a “print entire section” feature (as seen in this user guide). Selecting this option renders the entire current top-level section (such as Content and Customization for this page) with all of its child pages and sections in a format suited to printing, complete with a table of contents for the section.

To enable this feature, add the “print” output format in your site’s config.toml/config.yaml/config.json file for the “section” type:

• Configuration file:
• config.toml
• config.yaml
• config.json

[outputs]
section = [ "HTML", "RSS", "print" ]

outputs:
  section:
    - HTML
    - RSS
    - print

{
  "outputs": {
    "section": [
      "HTML",
      "RSS",
      "print"
    ]
  }
}

The site should then show a “Print entire section” link in the right hand navigation.

Further Customization

Disabling the ToC

To disable showing the the table of contents in the printable view, set the disable_toc param to true, either in the page front matter, or in config.toml/config.yaml/config.json:

• Front matter:
• toml
• yaml
• json
• or config file:
• config.toml
• config.yaml
• config.json