This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Welcome to Docsy

Welcome to the Docsy theme user guide! This guide shows you how to get started creating technical documentation sites using Docsy, including site customization and how to use Docsy’s blocks and templates.

What is Docsy?

Docsy is a theme for the Hugo static site generator that’s specifically designed for technical documentation sets and has a lot of best practices built in. Use Docsy to get a working and reliable documentation site up and running fast, and then get back to focusing on great content for your users. Learn more about Docsy.

In addition to the theme itself, we provide an example site that uses lots of Docsy features and has a useful skeleton site structure (with advice for what to put in it!) for a large technical documentation set. You can copy the entire site and edit it for your own projects, or just explore the site and its source to see what Docsy can do. The site you’re currently reading also uses Docsy and is a useful example of a smaller Docsy docset: feel free to copy it or borrow from it if it suits your needs better than the “big” example.

Docsy itself does not provide:

  • Source hosting and management: Our theme and site source files live on GitHub, which is the simplest approach for most projects. However, you can also keep your project files in GitLab, BitBucket, locally, or wherever you like. Be aware that where your source files live may affect the Docsy features you can use (such as letting users file documentation issues) and site deployment options.
  • Site deployment: You can find out about deployment options in Previews and Deployment. This site uses Netlify.

Docsy also doesn’t actually generate your site’s HTML files: that’s Hugo’s job! Hugo takes your Markdown or HTML doc source files and Docsy’s theme files and builds them into a static site for deployment. You can find out more about Hugo and how it works in the Hugo documentation.

Is Docsy for me?

Docsy is particularly useful for medium to large technical documentation sets with 20+ pages of docs and/or multiple types of docs and pages: tutorials, reference documentation, blog posts, community pages, and so on.

If you have a smaller project with only a couple of pages of documentation and hence simpler navigation needs, Docsy may be too heavyweight a solution for you. Instead, consider:

  • A simpler Hugo or Jekyll theme: find out what’s available in Github Pages' built-in Jekyll options and the Hugo theme gallery.
  • A good README file that tells users what your project does and links to some examples.

If you have a very large documentation project, our example site structure may not be sufficient either, though you can still use our theme, possibly with heavier customization.

If you’d like to use Docsy’s layouts but prefer to use Jekyll, vsoch has created a Docsy Jekyll port that includes many of Docsy’s features (though as this is a separate project it won’t be automatically updated along with Docsy).

Ready to get started?

Find out how to build and serve your first site in Getting Started. Or visit the example site and its repo and start exploring!

1 - Getting Started

This page tells you how to get started with the Docsy theme, including installation and basic configuration.

Prerequisites and installation

Use our Docker image

We provide a Docker image that you can use to run and test your Docsy site locally, without having to install all Docsy’s dependencies.

You can see how to get started with this approach by following our Docker Quickstart tutorial. If you don’t want to use Docker, follow the instructions below to install Hugo and PostCSS.

Install Hugo

You need a recent extended version (we recommend version 0.75.0 or later) of Hugo to do local builds and previews of sites (like this one) that use Docsy. If you install from the release page, make sure to get the extended Hugo version, which supports SCSS; you may need to scroll down the list of releases to see it.

For comprehensive Hugo documentation, see


Be careful using sudo apt-get install hugo, as it doesn’t get you the extended version for all Debian/Ubuntu versions, and may not be up-to-date with the most recent Hugo version.

If you’ve already installed Hugo, check your version:

hugo version

If the result is v0.75 or earlier, or if you don’t see Extended, you’ll need to install the latest version. You can see a complete list of Linux installation options in Install Hugo. The following shows you how to install Hugo from the release page:

  1. Go to the Hugo releases page.

  2. In the most recent release, scroll down until you find a list of Extended versions.

  3. Download the latest extended version (hugo_extended_0.5X_Linux-64bit.tar.gz).

  4. Create a new directory:

    mkdir hugo
  5. Extract the files you downloaded to hugo.

  6. Switch to your new directory:

    cd hugo
  7. Install Hugo:

    sudo install hugo /usr/bin    


Install Hugo using Brew.

As an npm module

You can install Hugo as an npm module using hugo-bin. This adds hugo-bin to your node_modules folder and adds the dependency to your package.json file. To install the extended version of Hugo:

npm install hugo-extended --save-dev

See the hugo-bin documentation for usage details.

Install PostCSS

To build or update your site’s CSS resources, you also need PostCSS to create the final assets. If you need to install it, you must have a recent version of NodeJS installed on your machine so you can use npm, the Node package manager. By default npm installs tools under the directory where you run npm install:

npm install -D autoprefixer
npm install -D postcss-cli

Starting in version 8 of postcss-cli, you must also separately install postcss:

npm install -D postcss

Note that versions of PostCSS later than 5.0.1 will not load autoprefixer if installed globally, you must use a local install.

Using the theme

To use the Docsy Hugo theme, you have a couple of options:

  • Copy and edit the source for the Docsy example site. This approach gives you a skeleton structure for your site, with top-level and documentation sections and templates that you can modify as necessary. The example site uses Docsy as a Git submodule, so it’s easy to keep up to date.
  • Build your own site using the Docsy theme. Specify the Docsy theme like any other Hugo theme when creating or updating your site. With this option, you’ll get Docsy look and feel, navigation, and other features, but you’ll need to specify your own site structure.

Option 1: Copy the Docsy example site

The Example Site gives you a good starting point for building your docs site and is pre-configured to use the Docsy theme as a Git submodule. You can copy the Example Site either by:

Using the GitHub UI

This is the simplest approach, as the Docsy example site repo is a template repository. To create your own copy of the Docsy example site repo:

  1. Go to the repo page and click Use this template.

  2. Type your chosen name for your new repository in the Repository name field. You can also add an optional Description.

  3. Click Create repository from template to create your new repository. Congratulations, you now have a Docsy site repo!

  4. To test your copied site locally with Hugo, or make local edits, you’ll also need to make a local copy of your new repository. To do this, use git clone, replacing with your repo’s web URL (don’t forget to use --recurse-submodules or you won’t pull down some of the code you need to generate a working site):

     git clone --recurse-submodules --depth 1

You can now edit your local versions of the site’s source files. To preview your site, go to your site root directory and run hugo server (see the known issues on MacOS). By default, your site will be available at http://localhost:1313/. To push changes to your new repo, go to your site root directory and use git push.

Using the command line

To copy the example site:

  1. Make a local working copy of the example site directly using git clone:

    git clone
  2. Switch to the root of the cloned project, for example:

     cd docsy-example
  3. Get local copies of the project submodules so you can build and run your site locally:

     git submodule update --init --recursive
  4. Build your site:

     hugo server
  5. Preview your site in your browser at: http://localhost:1313/. You can use Ctrl + c to stop the Hugo server whenever you like. See the known issues on MacOS.

  6. Now that you have a site running, you can push it to a new repository:

    1. Create a new repository in GitHub for your site with your chosen repo name. For clarity you may also want to rename the root directory (docsy-example) of your working copy to match, though everything will still work even if you don’t.

    2. Configure origin in your project. From your site’s root directory, set the URL for origin to your new repo (otherwise you’ll be trying to push changes to google/docsy rather than to your repo):

        git remote set-url origin
    3. Verify that your remote is configured correctly by running:

        git remote -v
    4. Push your Docsy site to your repository:

        git push -u origin master

Option 2: Use the Docsy theme in your own site

Specify the Docsy theme like any other Hugo theme when creating or updating your site. This gives you all the theme-y goodness but you’ll need to specify your own site structure. You can either use the theme as a submodule (our recommended approach for easy updates), or just clone the theme into your project’s themes subdirectory.

Whichever approach you use, for simplicity we recommend copying and editing our example site configuration for your project, or you may get Hugo errors for missing parameters and values when you try to build your site.

Using the Docsy theme as a submodule

Adding Docsy as a Git submodule is our recommended approach for using the theme, as it means your project always refers to the Docsy repo version at your chosen revision, rather than you having your own copy in your repo that may result in merge conflicts when you try to update it. This is the approach used by our example project.

To create a new Hugo site project and then add the Docs theme as a submodule, run the following commands from your project’s root directory.

hugo new site myproject
cd myproject
git init
git submodule add themes/docsy
echo 'theme = "docsy"' >> config.toml
git submodule update --init --recursive

To add the Docsy theme to an existing site, run the following commands from your project’s root directory:

git submodule add themes/docsy
echo 'theme = "docsy"' >> config.toml
git submodule update --init --recursive

Cloning the Docsy theme to your project’s themes subdirectory

If you don’t want to use a submodules (for example, if you want to customize and maintain your own copy of the theme directly, or your deployment choice requires you to include a copy of the theme in your repository), you can clone the theme into your project.

To clone Docsy into your project’s theme folder, run the following commands from your project’s root directory:

cd themes
git clone

If you want to build and/or serve your site locally, you also need to get local copies of the theme’s own submodules:

git submodule update --init --recursive

For more information, see Theme Components on the Hugo site.

Preview your site

To build and preview your site locally:

cd myproject
hugo server

By default, your site will be available at http://localhost:1313/. See the known issues on MacOS.

Basic site configuration

Site-wide configuration details and parameters are defined in your project’s config.toml file. These include your chosen Hugo theme (Docsy, of course!), project name, community links, Google Analytics configuration, and Markdown parser parameters. See the examples with comments in config.toml in the example project for how to add this information. We recommend copying this config.toml and editing it even if you’re just using the theme and not copying the entire Docsy example site.

The Docsy example site comes with some defaults you may want to remove or customize straight away:


The Docsy example site supports content in English, Norwegian and Farsi. You can find out more about how Docsy supports multi-language content in Multi-language support.

If you don’t intend to translate your site, you can remove the language switcher by removing the following lines from config.toml:

title = "Docsy"
description = "Docsy er operativsystem for skyen"
languageName ="Norsk"
contentDir = "content/no"
time_format_default = "02.01.2006"
time_format_blog = "02.01.2006"

title = "اسناد گلدی"
description = "یک نمونه برای پوسته داکسی"
languageName ="فارسی"
contentDir = "content/fa"
time_format_default = "2006.01.02"
time_format_blog = "2006.01.02"

To remove the translated source files, delete both the docsy-example/content/no and the docsy-example/content/fa directory.

By default, the Docsy example site uses its own Google Custom Search Engine. To disable this site search, delete or comment out the following lines:

# Google Custom Search Engine ID. Remove or comment out to disable search.
gcs_engine_id = "011737558837375720776:fsdu1nryfng"

To use your own Custom Search Engine, replace the value in the gcs_engine_id with the ID of your own search engine. Or choose another search option.

Known issues


Errors: too many open files or fatal error: pipe failed

By default, MacOS permits a small number of open File Descriptors. For larger sites, or when you’re simultaneously running multiple applications, you might receive one of the following errors when you run hugo server to preview your site locally:

  • POSTCSS v7 and earlier:

    ERROR 2020/04/14 12:37:16 Error: listen tcp socket: too many open files
  • POSTCSS v8 and later:

    fatal error: pipe failed

To temporarily allow more open files:

  1. View your current settings by running:

    sudo launchctl limit maxfiles
  2. Increase the limit to 65535 files by running the following commands. If your site has fewer files, you can set choose to set lower soft (65535) and hard (200000) limits.

    sudo launchctl limit maxfiles 65535 200000
    ulimit -n 65535
    sudo sysctl -w kern.maxfiles=200000
    sudo sysctl -w kern.maxfilesperproc=65535

Note that you might need to set these limits for each new shell. Learn more about these limits and how to make them permanent.

Windows Subsystem for Linux (WSL)

If you’re using WSL, ensure that you’re running hugo on a Linux mount of the filesystem, rather than a Windows one, otherwise you may get unexpected errors.

What’s next?

1.1 - Docker Quickstart

This page helps you to setup and run a local Docsy site with Docker in 5 minutes.

Install the prerequisites

  1. On Mac and Windows, download and install Docker Desktop. On Linux, install Docker engine and Docker compose.

    The installation may require you to reboot your computer for the changes to take effect.

  2. Install git.

Create your repository from the docsy-example template

The docsy-example repository provides a basic site structure that you can use as starting point to create your own documentation.

  1. Use the docsy-example template to create your own repository.

  2. Download the code to your local machine by cloning your newly created repository.

  3. Change your working directory to the newly created folder:

    cd docsy-example

Build and run the container

The docsy-example repository includes a Dockerfile that you can use to run your site.

  1. Build the docker image:

    docker-compose build
  2. Run the built image:

    docker-compose up
  3. Open the address http://localhost:1313 in your web browser to load the docsy-example homepage. You can now make changes to the source files, those changes will be live-reloaded in your browser.


To cleanup your system and delete the container image follow the next steps.

  1. Stop Docker Compose with Ctrl + C.

  2. Remove the produced images

    docker-compose rm

What’s next?

2 - Content and Customization

How to add content to and customize your Docsy site.

2.1 - Adding Content

Add different types of content to your Docsy site.

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

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

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

title: "Latest News"
linkTitle: "News"
    weight: 30

- type: "blog"

If you want to create a “docs” site, specifying something like the following in the top level will set all top level sections to be treated as “docs”, except for “news”:

title: "My Wonderful Site"

- type: "blog"
  toc_root: true
    path: "/news/**"
- type: "docs"
    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:

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

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. Versions of Hugo before 0.60 use BlackFriday as its Markdown parser. From 0.60, Hugo uses Goldmark as its Markdown parser by default.

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.

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/ However the source for Docsy Shortcodes in this site lives in /content/en/docs/adding-content/shortcodes/, 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 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 (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 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 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:

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:

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

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

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

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
- src: "**.{png,jpg}"
  title: "Image #:counter"
    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, 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.

# End user relevant links. These will show up on left side of footer and in the community page if you have one.
	name = "User mailing list"
	url = ""
	icon = "fa fa-envelope"
        desc = "Discussion and help from your fellow users"
	name ="Twitter"
	url = ""
	icon = "fab fa-twitter"
        desc = "Follow us on Twitter to get the latest news!"
	name = "Stack Overflow"
	url = ""
	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.
	name = "GitHub"
	url = ""
	icon = "fab fa-github"
        desc = "Development takes place here!"
	name = "Slack"
	url = ""
	icon = "fab fa-slack"
        desc = "Chat with other project developers"
	name = "Developer mailing list"
	url = ""
	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/ 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. This is the default configuration:

rss_sections = ["blog"]

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

disableKinds = ["RSS"]


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:

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

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

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

To learn more about configuring sitemaps, see Sitemap Template.

2.2 - Look and Feel

Customize colors, fonts, code highlighting, and more for your site.

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

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;


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>
Background: Primary
Background: Gray 200

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

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

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:

      unsafe = true
      # See a complete list of available styles at
      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.

# Uncomment if you want your chosen highlight style used for code blocks without a specified language
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:

# Enable syntax highlighting and copy buttons on code blocks with Prism
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:

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

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.

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:


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:


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">
    {{ partial "head.html" . }}
  <body class="td-{{ .Kind }}">
      {{ partial "navbar.html" . }}
    <div class="container-fluid td-default td-outer">
      <main role="main" class="td-main">
        {{ block "main" . }}{{ end }}
      {{ partial "footer.html" . }}
    {{ partialCached "scripts.html" . }}

2.3 - Navigation and Search

Customize site navigation and search for your Docsy site.

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.

To add a page or section to this menu, add it to the site’s main menu in either config.toml or in the destination page’s front matter (in 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:

title: "Welcome to Docsy"
linkTitle: "Documentation"
    weight: 20
    pre: <i class='fas 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, specifying the weight.

    name = "GitHub"
    weight = 50
    url = ""

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

    name = "GitHub"
    weight = 50
    url = ""
    pre = "<i class='fab 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 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:

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

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.

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.

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: fas fa-tools).

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.

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 is enabled by default. To disable breadcrumb navigation, set site param ui.breadcrumb_disable = true in config.toml.

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).

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:

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.

  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/ (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:

    title: Search Results
    layout: search
  2. Add your Google Custom Search Engine ID to the site params in config.toml. You can add different values per language if needed.

    # Google Custom Search Engine ID. Remove or comment out to disable search.
    gcs_engine_id = "011737558837375720776:fsdu1nryfng"

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.

Sign up for Algolia DocSearch

Complete the form at

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

Adding Algolia DocSearch

  1. Enable Algolia DocSearch in config.toml.

    # Enable Algolia DocSearch
    algolia_docsearch = true
  2. Remove or comment out any GCSE ID in config.toml 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 as this is not currently supported for Algolia DocSearch. See Disabling the sidebar search box.

  4. Add the JavaScript code provided to you by Algolia to the head and body of every page on your site. See Add code to head or before body end for details.

  5. Update the inputSelector field in the body end Javascript with the appropriate CSS selector (e.g. .td-search-input to use the default CSS from this theme).

When you’ve completed these steps the Algolia search should be enabled on your site. Search results are displayed as a drop-down under the search box, 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.

    # Enable local search
    offlineSearch = true
  2. Remove or comment out any GCSE ID in config.toml 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.

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

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

#Enable offline search with Lunr.js
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.

body {
    .popover.offline-search-result {
        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:

title: "Index"
weight: 10
exclude_search: true

2.4 - Doc Versioning

Customize navigation and banners for multiple versions of your docs.

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

# Add your release versions here
  version = "master"
  url = ""

  version = "v0.2"
  url = ""

  version = "v0.3"
  url = ""

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:

version_menu = "Releases"

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:

A text box explaining that this is an unmaintained snapshot of the docs.
Figure 1. The banner on the archived docs for Kubeflow v0.6

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

  1. Set the archived_version parameter to 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:

    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:

    url_latest_version = ""

2.5 - Docsy Shortcodes

Use Docsy’s Hugo shortcodes to quickly build site pages.

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:

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


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="fas fa-arrow-alt-circle-right ml-2"></i>
	<a class="btn btn-lg btn-secondary mr-3 mb-4" href="">
		Download <i class="fab fa-github ml-2 "></i>
	<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" >}}
{{< /blocks/cover >}}

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

Parameter Default Description
title The main display title for the block.
height See above.
color See above.
byline Byline text on featured image.

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.


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 %}}
Parameter Default Description
height See above.
color See above.


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="fab fa-github" title="Contributions welcome!" url="" %}}
We do a [Pull Request]( contributions workflow on **GitHub**. New users are always welcome!
{{% /blocks/feature %}}
{{% blocks/feature icon="fab fa-twitter" title="Follow us on Twitter!" url="" %}}
For announcement of latest features etc.
{{% /blocks/feature %}}
{{< /blocks/section >}}
Parameter Default Description
height See above.
color See above.
type Specify “section” if you want a general container, omit this parameter if you want this section to contain a horizontal row of features.


{{% blocks/feature icon="fab fa-github" title="Contributions welcome!" url="" %}}
We do a [Pull Request]( contributions workflow on **GitHub**. New users are always welcome!
{{% /blocks/feature %}}

Parameter Default Description
title The title to use.
url The URL to link to.
icon The icon class to use.

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" >}}
Parameter Default Description
color info See above.

Shortcode helpers


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:

Parameter Default Description
color primary One of the theme colors, eg primary, info, warning etc.


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:

This is placeholder content

Parameter Default Description
color primary One of the theme colors, eg primary, info, warning etc.


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 >}}

Norway Spruce Picea abies shoot with foliage buds.
Photo: Bjørn Erik Pedersen / CC-BY-SA

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:

- src: "**spruce*.jpg"
    byline: "Photo: Bjørn Erik Pedersen / CC-BY-SA"
Parameter Description
1 The image filename or enough of it to identify it (we do Glob matching)
2 Command. One of Fit, Resize or Fill. See Image Processing Methods.
3 Processing options, e.g. 400x450. See Image Processing Options.


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 can be hosted anywhere you like, for example in your site’s root /static folder.

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.


With this shortcode you can embed external content into a Docsy page as an inline frame (iframe) - see:

Parameter Default Description
src URL of external content
width 100% Width of iframe
tryautoheight true If true the shortcode tries to calculate the needed height for the embedded content using JavaScript, as described here: This is only possible if the embedded content is on the same domain. Note that even if the embedded content is on the same domain, it depends on the structure of the content if the height can be calculated correctly.
style min-height:98vh; border:none; CSS styles for the iframe. min-height:98vh; is a backup if tryautoheight doesn’t work. border:none; removes the border from the iframe - this is useful if you want the embedded content to look more like internal content from your page.
sandbox false You can switch the sandbox completely on by setting sandbox = true or allow specific functionality with the common values for the iframe parameter sandbox defined in the HTML standard.
name iframe-name Specify the name of the iframe.
id iframe-id Sets the ID of the iframe.
class Optional parameter to set the classes of the iframe.
sub Your browser cannot display embedded frames. You can access the embedded page via the following link: The text displayed (in addition to the embedded URL) if the user’s browser can’t display embedded frames.

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 table below shows the language-specific variants of the famous Hello world! program one usually writes first when learning a new programming language from scratch:

#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"
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 pane with three tabs:

{{< tabpane >}}
  {{< tab header="English" >}}
  {{< /tab >}}
  {{< tab header="German" >}}
    Herzlich willkommen!
  {{< /tab >}}
  {{< tab header="Swahili" >}}
    Karibu sana!
  {{< /tab >}}
{{< /tabpane >}}

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

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 optionally held 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 blocks of the individual 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 language parameter of the respective tab.
  • The various tab shortcodes which actually represent the tabs you would like to show. We recommend specifying the named parameter header for each text in order to set the header text of each tab. If needed, you can additionally specify the named parameters lang and highlight for each tab. This allows you to overwrite the settings given in the parent tabpane shortcode. If the language is neither specified in the tabpane nor in the tabshortcode, it defaults to Hugo’s site variable .Site.Language.Lang.

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

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.

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

Java 5

File[] hiddenFiles = new File("directory_name")
  .listFiles(new FileFilter() {
    public boolean accept(File file) {
      return file.isHidden();
Java 8, Lambda expression

File[] hiddenFiles = new File("directory_name")

2.6 - Logos and Images

Add and customize logos, icons, and images in your project.

Add your project logo as assets/icons/logo.svg in your project. This overrides the default Docsy logo in the theme. If you don’t want a project logo, set navbar_logo to false (or delete the variable) in your config.toml:

navbar_logo = false

If you decide at a later stage that you’d like to add a logo to your navbar, you can set the parameter to true:

navbar_logo = true

Add your favicons

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

Note that 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.

2.7 - Print Support

Making it easier to print entire sections of documentation.

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 file for the “section” type:

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:

disable_toc = true

Layout hooks

A number of layout partials and hooks are defined that can be used to customize the printed format. These can be found in layouts/partials/print.

Hooks can be defined on a per-type basis. For example, you may want to customize the layouts of heading for “blog” pages vs “docs”. This can be achieved by creating layouts/partials/print/page-heading-<type>.html - eg. page-heading-blog.html. It defaults to using the page title and description as a heading.

Similarly, the formatting for each page can be customized by creating layouts/partials/print/content-<type>.html.

2.8 - Analytics, User Feedback, SEO

Add Google Analytics tracking to your site, use the “was this page helpful?” widget data, disable the widget on a single page or all pages, and change the response text. See what data is used to create the meta description tag for SEO.

Adding Analytics

The Docsy theme contains built-in support for Google Analytics via Hugo’s internal template, which is included in the theme. Once you set Analytics up as described below, usage information for your site (such as page views) is sent to your Google Analytics account.


  1. Ensure you have set up a Google Analytics property for your site: this gives you an Analytics ID to add to your config, which Docsy in turn adds to all your site’s pages.

  2. Open config.toml.

  3. Enable Google Analytics by setting the Tracking ID property to your site’s Analytics ID.

     id = "UA-00000000-0"
  4. Save and close config.toml.

  5. Ensure that your site is built with HUGO_ENV="production", as Docsy only adds Analytics tracking to production-ready sites. You can specify this variable as a command line flag to Hugo:

    $ env HUGO_ENV="production" hugo

    Alternatively, if you’re using Netlify, you can specify it as a Netlify deployment setting in netlify.toml or the Netlify UI, along with the Hugo version.

User Feedback

By default Docsy puts a “was this page helpful?” feedback widget at the bottom of every documentation page, as shown in Figure 1.

The user is presented with the text 'Was this page helpful?' followed
            by 'Yes' and 'No' buttons.
Figure 1. The feedback widget, outlined in red

After clicking Yes the user should see a response like Figure 2. You can configure the response text in config.toml.

After clicking 'Yes' the widget responds with 'Glad to hear it!
            Please tell us how we can improve.' and the second sentence is a link which,
            when clicked, opens GitHub and lets the user create an issue on the
            documentation repository.
Figure 2. An example Yes response

How is this data useful?

When you have a lot of documentation, and not enough time to update it all, you can use the “was this page helpful?” feedback data to help you decide which pages to prioritize. In general, start with the pages with a lot of pageviews and low ratings. “Low ratings” in this context means the pages where users are clicking No — the page wasn’t helpful — more often than Yes — the page was helpful. You can also study your highly-rated pages to develop hypotheses around why your users find them helpful.

In general, you can develop more certainty around what patterns your users find helpful or unhelpful if you introduce isolated changes in your documentation whenever possible. For example, suppose that you find a tutorial that no longer matches the product. You update the instructions, check back in a month, and the score has improved. You now have a correlation between up-to-date instructions and higher ratings. Or, suppose you study your highly-rated pages and discover that they all start with code samples. You find 10 other pages with their code samples at the bottom, move the samples to the top, and discover that each page’s score has improved. Since this was the only change you introduced on each page, it’s more reasonable to believe that your users find code samples at the top of pages helpful. The scientific method, applied to technical writing, in other words!


  1. Open config.toml.

  2. Ensure that Google Analytics is enabled, as described above.

  3. Set the response text that users see after clicking Yes or No.

     enable = true
     yes = 'Glad to hear it! Please <a href="">tell us how we can improve</a>.'
     no = 'Sorry to hear that. Please <a href="">tell us how we can improve</a>.'
  4. Save and close config.toml.

Access the feedback data

This section assumes basic familiarity with Google Analytics. For example, you should know how to check pageviews over a certain time range and navigate between accounts if you have access to multiple documentation sites.

  1. Open Google Analytics.
  2. Open Behavior > Events > Overview.
  3. In the Event Category table click the Helpful row. Click view full report if you don’t see the Helpful row.
  4. Click Event Label. You now have a page-by-page breakdown of ratings.

Here’s what the 4 columns represent:

  • Total Events is the total number of times that users clicked either Yes or No.
  • Unique Events provides a rough indication of how frequently users are rating your pages per session. For example, suppose your Total Events is 5000, and Unique Events is 2500. This means that you have 2500 users who are rating 2 pages per session.
  • Event Value isn’t that useful.
  • Avg. Value is the aggregated rating for that page. The value is always between 0 and 1. When users click No a value of 0 is sent to Google Analytics. When users click Yes a value of 1 is sent. You can think of it as a percentage. If a page has an Avg. Value of 0.67, it means that 67% of users clicked Yes and 33% clicked No.

The underlying Google Analytics infrastructure that stores the “was this page helpful?” data is called Events. See docsy pull request #1 to see exactly what happens when a user clicks Yes or No. It’s just a click event listener that fires the Google Analytics JavaScript function for logging an Event, disables the Yes and No buttons, and shows the response text.

Disable feedback on a single page

Add hide_feedback: true to the page’s front matter.

Disable feedback on all pages

Set to false in config.toml:

enable = false

Search Engine Optimization meta tags

Check out Google’s Search Engine Optimization (SEO) Starter Guide for how to optimize your site for SEO.

Google recommends using the description meta tag to tell search engines what your page is about. The Docsy theme creates and populates this meta tag for you in the layouts/partials/head.html file:

{{ if .Page.Description }}
  <meta name="description" content="{{ .Page.Description }}">
{{ else }}
  {{ $desc := (.Page.Content | safeHTML | truncate 150) }}
  <meta name="description" content="{{ $desc }}">
{{ end }}

.Page.Description is the text from the description frontmatter field. If the page’s frontmatter does not have a description, the first 150 characters of the page content is used instead.

For example, if your front matter description is:

description: >
  Add Google Analytics tracking to your site.

Then the meta description tag on the rendered page is:

<meta name="description" content="Add Google Analytics tracking to your site.">

You can add additional meta tags to your own copy of the head-end.html partial. See Customizing templates for more information.

2.9 - Repository Links

Help your users interact with your source repository.

The Docsy docs and blog layouts include links for readers to edit the page or create issues for your docs or project via your site’s source repository. The current generated links for each docs or blog page are:

  • View page source: Brings the user to the page source in your docs repo.
  • Edit this page: Brings the user to an editable version of the page content in their fork (if available) of your docs repo. If the user doesn’t have a current fork of your docs repo, they are invited to create one before making their edit. The user can then create a pull request for your docs.
  • Create child page: Brings the user to a create new file form in their fork of your docs repo. The new file will be located as a child of the page they clicked the link on. The form will be pre-populated with a template the user can edit to create their page. You can change this by adding assets/stubs/ to your own project.
  • Create documentation issue: Brings the user to a new issue form in your docs repo with the name of the current page as the issue’s title.
  • Create project issue (optional): Brings the user to a new issue form in your project repo. This can be useful if you have separate project and docs repos and your users want to file issues against the project feature being discussed rather than your docs.

This page shows you how to configure these links.

Currently, Docsy supports only GitHub repository links “out of the box”. If you are using another repository such as Bitbucket and would like generated repository links, feel free to add a feature request or update our theme.

There are four variables you can configure in config.toml to set up links, as well as one in your page metadata.


The URL for your site’s source repository. This is used to generate the Edit this page, Create child page, and Create documentation issue links.

github_repo = ""

github_subdir (optional)

Specify a value here if your content directory is not in your repo’s root directory. For example, this site is in the userguide subdirectory of its repo. Setting this value means that your edit links will go to the right page.

github_subdir = "userguide"

github_project_repo (optional)

Specify a value here if you have a separate project repo and you’d like your users to be able to create issues against your project from the relevant docs. The Create project issue link appears only if this is set.

github_project_repo = ""

github_branch (optional)

Specify a value here if you have would like to reference a different branch for the other github settings like Edit this page or Create project issue.

github_branch = "release"

path_base_for_github_subdir (optional)

Suppose that the source files for all of the pages under content/some-section come from another repo, such as a git submodule. Add settings like these to the section’s index page so that the repository links for all pages in that section refer to the originating repo:

title: Some super section
  github_subdir: docs
  path_base_for_github_subdir: content/some-section

As an example, consider a page at the path content/some-section/subpath/ with github_branch globally set to main. The index page settings above will generate the following edit link for

If you only have a single page originating from another repo, then omit the cascade key and write, at the top-level, the same settings as illustrated above.

If you’d like users to create project issues in the originating repo as well, then also set github_project_repo, something like this:

  github_repo: &repo
  github_project_repo: *repo

Using a Yaml anchor is optional, but it helps keep the settings DRY.

The path_base_for_github_subdir setting is a regular expression, so you can use it even if you have a site with multiple languages for example:

path_base_for_github_subdir: content/\w+/some-section

In situations where a page originates from a file under a different name, you can specify from and to path-rename settings. Here’s an example where an index file is named in the originating repo:

github_subdir: docs
  from: content/some-section/(.*?)/
  to: $1/

github_url (optional)

Specify a value for this in your page metadata to set a specific edit URL for this page, as in the following example:

title: Some page

This can be useful if you have page source files in multiple Git repositories, or require a non-GitHub URL. Pages using this value have Edit this page links only.

You can use CSS to selectively disable (hide) links. For example, add the following to your projects’s _styles_project.scss file to hide Create child page links from all pages:

.td-page-meta--child { display: none !important; }

Each link kind has an associated unique class named .td-page-meta--KIND, as defined by the following table:

Link kind Class name
View page source .td-page-meta--view
Edit this page .td-page-meta--edit
Create child page .td-page-meta--child
Create documentation issue .td-page-meta--issue
Create project issue .td-page-meta--project-issue

Of course, you can also use these classes to give repository links unique styles for your project.

2.10 - Taxonomy Support

Structure the content using taxonomies like tags, categories, labels.

Docsy supports Hugo’s Taxonomies (see: in its docs and blog section. You can see the default layout and can test the behavior of the generated links on this page.


To understand the usage of taxonomies you should understand the following terminology:

a categorization that can be used to classify content - e.g.: Tags, Categories, Projects, People
a key within the taxonomy - e.g. within projects: Project A, Project B
a piece of content assigned to a term - e.g. a page of your site, that belongs to a specific project

A example taxonomy for a movie website you can find in the official Hugo docs:


There are various parameter to control the functionality of taxonomies in the config.toml.

By default taxonomies for tags and categories are enabled in Hugo (see: In Docsy taxonomies are disabled by default in the config.toml:

disableKinds = ["taxonomy", "taxonomyTerm"]

If you want to enable taxonomies in Docsy you have to delete (or comment out) this line in your projects config.toml. Then the taxonomy pages for tags and categories will be generated by Hugo. If you want to use other taxonomies you have to define them in your config.toml. If you want to use beside your own taxonomies also the default taxonomies tags and categories, you also have to define them beside your own taxonomies. You need to provide both the plural and singular labels for each taxonomy.

With the following example you define a additional taxonomy projects beside the default taxonomies tags and categories:

tag = "tags"
category = "categories"
project = "projects"

You can use the following parameters in your projects config.toml to control the output of the assigned taxonomy terms for each article resp. page of your docs and/or blog section in Docsy or a “tag cloud” in Docsy’s right sidebar:

taxonomyCloud = ["projects", "tags"] # set taxonomyCloud = [] to hide taxonomy clouds
taxonomyCloudTitle = ["Our Projects", "Tag Cloud"] # if used, must have same lang as taxonomyCloud
taxonomyPageHeader = ["tags", "categories"] # set taxonomyPageHeader = [] to hide taxonomies on the page headers

The settings above would only show a taxonomy cloud for projects and tags (with the headlines “Our Projects” and “Tag Cloud”) in Docsy’s right sidebar and the assigned terms for the taxonomies tags and categories for each page.

To disable any taxonomy cloud you have to set the Parameter taxonomyCloud = [] resp. if you doesn’t want to show the assigned terms you have to set taxonomyPageHeader = [].

As default the plural label of a taxonomy is used as it cloud title. You can overwrite the default cloud title with taxonomyCloudTitle. But if you do so, you have to define a manual title for each enabled taxonomy cloud (taxonomyCloud and taxonomyCloudTitle must have the same length!).

If you doesn’t set the parameters taxonomyCloud resp. taxonomyPageHeader the taxonomy clouds resp. assigned terms for all defined taxonomies will be generated.


The by default used partials for displaying taxonomies are so defined, that you should be able to use them also easily in your own layouts.


The partial taxonomy_terms_article shows all assigned terms of an given taxonomy (partial parameter taxo) of an article respectively page (partial parameter context, most of the time the current page or context .).

Example usage in layouts/docs/list.html for the header of each page in the docs section:

{{ $context := . }}
{{ range $taxo, $taxo_map := .Site.Taxonomies }}
  {{ partial "taxonomy_terms_article.html" (dict "context" $context "taxo" $taxo ) }}
{{ end }}

This will gave you for each in the current page (resp. context) defined taxonomy a list with all assigned terms:

<div class="taxonomy taxonomy-terms-article taxo-categories">
  <h5 class="taxonomy-title">Categories:</h5>
  <ul class="taxonomy-terms">
    <li><a class="taxonomy-term" href="//localhost:1313/categories/taxonomies/" data-taxonomy-term="taxonomies"><span class="taxonomy-label">Taxonomies</span></a></li>
<div class="taxonomy taxonomy-terms-article taxo-tags">
  <h5 class="taxonomy-title">Tags:</h5>
  <ul class="taxonomy-terms">
    <li><a class="taxonomy-term" href="//localhost:1313/tags/tagging/" data-taxonomy-term="tagging"><span class="taxonomy-label">Tagging</span></a></li>
    <li><a class="taxonomy-term" href="//localhost:1313/tags/structuring-content/" data-taxonomy-term="structuring-content"><span class="taxonomy-label">Structuring Content</span></a></li>
    <li><a class="taxonomy-term" href="//localhost:1313/tags/labelling/" data-taxonomy-term="labelling"><span class="taxonomy-label">Labelling</span></a></li>


The partial taxonomy_terms_cloud shows all used terms of an given taxonomy (partial parameter taxo) for your site (partial parameter context, most of the time the current page or context .) and with the parameter title as headline.

Example usage in partial taxonomy_terms_clouds for showing all defined taxonomies and its terms:

{{ $context := . }}
{{ range $taxo, $taxo_map := .Site.Taxonomies }}
  {{ partial "taxonomy_terms_cloud.html" (dict "context" $context "taxo" $taxo "title" ( humanize $taxo ) ) }}
{{ end }}

As an example this will gave you for following HTML markup for the taxonomy categories:

<div class="taxonomy taxonomy-terms-cloud taxo-categories">
  <h5 class="taxonomy-title">Cloud of Categories</h5>
  <ul class="taxonomy-terms">
    <li><a class="taxonomy-term" href="//localhost:1313/categories/category-1/" data-taxonomy-term="category-1"><span class="taxonomy-label">category 1</span><span class="taxonomy-count">3</span></a></li>
    <li><a class="taxonomy-term" href="//localhost:1313/categories/category-2/" data-taxonomy-term="category-2"><span class="taxonomy-label">category 2</span><span class="taxonomy-count">1</span></a></li>
    <li><a class="taxonomy-term" href="//localhost:1313/categories/category-3/" data-taxonomy-term="category-3"><span class="taxonomy-label">category 3</span><span class="taxonomy-count">2</span></a></li>
    <li><a class="taxonomy-term" href="//localhost:1313/categories/category-4/" data-taxonomy-term="category-4"><span class="taxonomy-label">category 4</span><span class="taxonomy-count">6</span></a></li>


The partial taxonomy_terms_clouds is a wrapper for the partial taxonomy_terms_cloud with the only parameter context (most of the time the current page or context .) and checks the taxonomy parameters of you projects config.toml to loop threw all listed taxonomies in the parameter taxonomyCloud resp. all defined taxonomies of your page, if taxonomyCloud isn’t set.

Multi language support for taxonomies

The taxonomy terms associated content gets only counted and linked WITHIN the language! The control parameters for the taxonomy support can also get assigned language specific.

2.11 - Diagrams and Formulae

Add generated diagrams and scientific formulae to your site.

Docsy has built-in support for a number of diagram creation and typesetting tools you can use to add rich content to your site, including \(\KaTeX\), Mermaid,, PlantUML, and MarkMap.

\(\LaTeX\) support with \(\KaTeX\)

\(\LaTeX\) is a high-quality typesetting system for the production of technical and scientific documentation. Due to its excellent math typesetting capabilities, \(\TeX\) became the de facto standard for the communication and publication of scientific documents, especially if these documents contain a lot of mathematical formulae. Designed and mostly written by Donald Knuth, the initial version was released in 1978. Dating back that far, \(\LaTeX\) has pdf as its primary output target and is not particularly well suited for producing HTML output for the Web. Fortunately, with \(\KaTeX\) there exists a fast and easy-to-use JavaScript library for \(\TeX\) math rendering on the web, which was integrated into the Docsy theme.

With \(\KaTeX\) support enabled in Docsy, you can include complex mathematical formulae into your web page, either inline or centred on its own line. Since \(\KaTeX\) relies on server side rendering, it produces the same output regardless of your browser or your environment. Formulae can be shown either inline or in display mode:

Inline formulae

The following code sample produces a text line with three inline formulae:

When \\(a \ne 0\\), there are two solutions to \\(ax2 + bx + c= 0\\) and they are \\(x = {-b \pm \sqrt{b^2-4ac} \over 2a}.\\)

When \(a \ne 0\), there are two solutions to \(ax2 + bx + c= 0\) and they are \(x = {-b \pm \sqrt{b^2-4ac} \over 2a}.\)

Formulae in display mode

The following code sample produces an introductory text line followed by a formula numbered as (1) residing on her own line:

The probability of getting \\(k\\) heads when flipping \\(n\\) coins is:
$$\tag*{(1)} P(E) = {n \choose k} p^k (1-p)^{n-k}$$

The probability of getting \(k\) heads when flipping \(n\) coins is: $$\tag*{(1)} P(E) = {n \choose k} p^k (1-p)^{n-k}$$

Enabling and configuring \(\LaTeX\) support

To enable/disable \(\KaTeX\) support inside the Docsy theme, update config.toml:

enable = true

Additionally, you can customize various \(\KaTeX\) options inside config.toml, if needed:

# enable/disable KaTeX support
enable = true
# Element(s) scanned by auto render extension. Default: document.body
html_dom_element = "document.body"

# If true (the default), KaTeX will throw a ParseError when it encounters an
# unsupported command or invalid LaTeX. If false, KaTeX will render unsupported
# commands as text, and render invalid LaTeX as its source code with hover text
# giving the error, in the color given by errorColor.
throwOnError = false
errorColor = "#CD5C5C"

# This is a list of delimiters to look for math, processed in the same order as
# the list. Each delimiter has three properties:
#   left:    A string which starts the math expression (i.e. the left delimiter).
#   right:   A string which ends the math expression (i.e. the right delimiter).
#   display: Whether math in the expression should be rendered in display mode.
  left = "$$"
  right = "$$"
  display = true
  left = "$"
  right = "$"
  display = false
  left = "\\("
  right = "\\)"
  display = false
  left = "\\["
  right = '\\]'
  display = true

For a complete list of options and their detailed description, have a look at the documentation of \({\KaTeX}’s\) Rendering API options and of \({\KaTeX}’s\) configuration options.

Display of Chemical Equations and Physical Units

mhchem is a \(\LaTeX\) package for typesetting chemical molecular formulae and equations. Fortunately, \(\KaTeX\) provides the mhchem extension that makes the mhchem package accessible when authoring content for the web. Since this extension was integrated into the Docsy theme, you can write beautiful chemical equations easily once mhchem support is enabled inside your config.toml:

enable = true

enable = true

With mhchem extension enabled, you can easily include chemical equations into your page. The equations can be shown either inline or can reside on its own line. The following code sample produces a text line including a chemical equation:

*Precipitation of barium sulfate:* \\(\ce{SO4^2- + Ba^2+ -> BaSO4 v}\\)

Precipitation of barium sulfate: \(\ce{SO4^2- + Ba^2+ -> BaSO4 v}\)

More complex equations, like the one shown in the code sample below, should be displayed on their own line:

$$\tag*{(2)} \ce{Zn^2+  <=>[+ 2OH-][+ 2H+]  $\underset{\text{amphoteric hydroxide}}{\ce{Zn(OH)2 v}}$  <=>[+ 2OH-][+ 2H+]  $\underset{\text{tetrahydroxozincate}}{\ce{[Zn(OH)4]^2-}}$}$$

$$\tag*{(2)} \ce{Zn^2+ <=>[+ 2OH-][+ 2H+] $\underset{\text{amphoteric hydroxide}}{\ce{Zn(OH)2 v}}$ <=>[+ 2OH-][+ 2H+] $\underset{\text{tetrahydroxozincate}}{\ce{[Zn(OH)4]^2-}}$}$$

Use of mhchem is not limited to the authoring of chemical equations, using the included \pu command, pretty looking physical units can be written with ease, too. The following code sample produces two text lines with four numbers plus their corresponding physical units:

* Scientific number notation: \\(\pu{1.2e3 kJ}\\) or \\(\pu{1.2E3 kJ}\\) \\
* Divisions: \\(\pu{123 kJ/mol}\\) or \\(\pu{123 kJ//mol}\\)
  • Scientific number notation: \(\pu{1.2e3 kJ}\) or \(\pu{1.2E3 kJ}\)
  • Divisions: \(\pu{123 kJ/mol}\) or \(\pu{123 kJ//mol}\)

For a complete list of options when authoring physical units, have a look at the section on physical units in the mhchem documentation.

Diagrams with Mermaid

Mermaid is a Javascript library for rendering simple text definitions to useful diagrams in the browser. It can generate a variety of different diagram types, including flowcharts, sequence diagrams, class diagrams, state diagrams, ER diagrams, user journey diagrams, Gantt charts and pie charts.

With Mermaid support enabled in Docsy, you can include the text definition of a Mermaid diagram inside a code block, and it will automatically be rendered by the browser as soon as the page loads.

The great advantage of this is anyone who can edit the page can now edit the diagram - no more hunting for the original tools and version to make a new edit.

For example, the following defines a simple flowchart:

graph LR
  Start --> Need{"Do I need diagrams"}
  Need -- No --> Off["Set params.mermaid.enable = false"]
  Need -- Yes --> HaveFun["Great!  Enjoy!"]

Automatically renders to:

graph LR
  Start --> Need{"Do I need diagrams"}
  Need -- No --> Off["Set params.mermaid.enable = false"]
  Need -- Yes --> HaveFun["Great!  Enjoy!"]

To enable/disable Mermaid, update config.toml:

enable = true

You also need to disable the guessSyntax from markup highlighting in config.toml for Mermaid to work:

      guessSyntax = "false"

You can also update settings for Mermaid, such as themes, padding, etc:

enable = true
theme = "neutral"

diagramPadding = 6

See the Mermaid documentation for a list of defaults that can be overridden.

Settings can also be overridden on a per-diagram basis by making use of the %%init%% header at the start of the diagram definition. See the Mermaid theming documentation.

UML Diagrams with PlantUML

PlantUML is an alternative to Mermaid that lets you quickly create UML diagrams, including sequence diagrams, use case diagrams, and state diagrams. Unlike Mermaid diagrams, which are entirely rendered in the browser, PlantUML uses a PlantUML server to create diagrams. You can use the provided default demo server (not recommended for production use), or run a server yourself. PlantUML offers a wider range of image types than Mermaid, so may be a better choice for some use cases.

Diagrams are defined using a simple and intuitive language. (see PlantUML Language Reference Guide).

The following example shows a use case diagram:

participant participant as Foo
actor       actor       as Foo1
boundary    boundary    as Foo2
control     control     as Foo3
entity      entity      as Foo4
database    database    as Foo5
collections collections as Foo6
queue       queue       as Foo7
Foo -> Foo1 : To actor 
Foo -> Foo2 : To boundary
Foo -> Foo3 : To control
Foo -> Foo4 : To entity
Foo -> Foo5 : To database
Foo -> Foo6 : To collections
Foo -> Foo7: To queue

Automatically renders to:

participant participant as Foo
actor       actor       as Foo1
boundary    boundary    as Foo2
control     control     as Foo3
entity      entity      as Foo4
database    database    as Foo5
collections collections as Foo6
queue       queue       as Foo7
Foo -> Foo1 : To actor 
Foo -> Foo2 : To boundary
Foo -> Foo3 : To control
Foo -> Foo4 : To entity
Foo -> Foo5 : To database
Foo -> Foo6 : To collections
Foo -> Foo7: To queue

To enable/disable PlantUML, update config.toml:

enable = true

Other optional settings are:

enable = true
theme = "default"

#Set url to plantuml server 
#default is
svg_image_url = ""

MindMap support with MarkMap

MarkMap is a Javascript library for rendering simple text definitions to MindMap in the browser.

For example, the following defines a simple MindMap:

# markmap

## Links

- <>
- [GitHub](

## Related

- [coc-markmap](
- [gatsby-remark-markmap](

## Features

- links
- **inline** ~~text~~ *styles*
- multiline
- `inline code`
    console.log('code block');
- Katex - $x = {-b \pm \sqrt{b^2-4ac} \over 2a}$

Automatically renders to:

# markmap

## Links

- <>
- [GitHub](

## Related

- [coc-markmap](
- [gatsby-remark-markmap](

## Features

- links
- **inline** ~~text~~ *styles*
- multiline
- `inline code`
    console.log('code block');
- Katex - $x = {-b \pm \sqrt{b^2-4ac} \over 2a}$

To enable/disable MarkMap, update config.toml:

enable = true

Diagrams with (aka provides a free and open source diagram editor that can generate a wider range of diagrams than Mermaid or PlantUML using a web or desktop editor.

SVG and PNG files exported with the tool contain the source code of the original diagram by default, which allows the site to import those images again for edit in the future. Docsy can detect this and automatically add an “edit” button over any image that can be edited using the online site.

Hover over the image below and click edit to instantly start working with it. Clicking the “Save” button will cause the edited diagram to be exported using the same filename and filetype, and downloaded to your browser.

As the diagram data is transported via the browser, the server does not need to access the content on your Docsy server directly at all.

Mouse over the above image and click the edit button!

Mouse over the above image and click the edit button!

To disable detection of diagrams, update config.toml:

enable = false

You can also deploy and use your own server for editing diagrams, in which case update the configuration to point to that server:

drawio_server = ""

3 - Multi-language Support

Support multiple languages in your site.

If you’d like to provide site content in multiple languages, the Docsy theme and Hugo make it easy to both add your translated content and for your users to navigate between language versions.

Content and configuration

To add content in multiple languages, you first need to define the available languages in a languages section in your site configuration. Each language can have its own language-specific configuration. For example, the Docsy Example Site config specifies that it provides content in English and Norwegian, and that the language version visitors will see by default is English:

contentDir = "content/en"
defaultContentLanguage = "en"
defaultContentLanguageInSubdir = false
title = "Docsy"
description = "Docsy does docs"
languageName ="English"
# Weight used for sorting.
weight = 1
title = "Docsy"
description = "Docsy er operativsystem for skyen"
languageName ="Norsk"
contentDir = "content/no"
time_format_default = "02.01.2006"
time_format_blog = "02.01.2006"

Any setting not defined in a [languages] block will fall back to the global value for that setting: so, for example, the content directory used for the site above will be content/en unless the user selects the Norwegian language option.

Once you’ve updated your site config, you create a content root directory for each language version in your source repo, such as content/en for English text, and add your content as usual. See the Hugo Docs on multi-language support for more information.

For adding multiple language versions of other site elements such as button text, see the internationalization bundles section below.

Selecting a language

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.

Internationalization bundles

All UI strings (text for buttons etc.) are bundled inside /i18n in the theme, with a .toml file for each language.

If your chosen language isn’t currently in the theme and you create your own .toml file for all the common UI strings (for example, if you translate the UI text into Japanese and create a copy of en.toml called jp.toml), we recommend you do this in the theme rather than in your own project, so it can be reused by others. Any additional strings or overridden values can be added to your project’s /i18n folder.

4 - Previews and Deployment

Deploying your Docsy site.

There are multiple possible options for deploying a Hugo site, including Netlify, Firebase Hosting, Bitbucket with Aerobatic, and more; you can read about them all in Hosting and Deployment. Hugo also makes it easy to deploy your site locally for quick previews of your content.

Serving your site locally

Depending on your deployment choice you may want to serve your site locally during development to preview content changes. To serve your site locally:

  1. Ensure you have an up to date local copy of your site files cloned from your repo. Don’t forget to use --recurse-submodules or you won’t pull down some of the code you need to generate a working site.

    git clone --recurse-submodules --depth 1
  2. Ensure you have the tools described in Prerequisites and installation installed on your local machine, including postcss-cli (you’ll need it to generate the site resources the first time you run the server).

  3. Run the hugo server command in your site root. By default your site will be available at http://localhost:1313/.

Now that you’re serving your site locally, Hugo will watch for changes to the content and automatically refresh your site. If you have more than one local git branch, when you switch between git branches the local website reflects the files in the current branch.

Build environments and indexing

By default, Hugo sites built with hugo (rather than served locally with hugo server) have the Hugo build environment production. Deployed Docsy sites with production builds can be indexed by search engines, including Google Custom Search Engines. Production builds also have optimized JavaScript and CSS for live deployment (for example, minified JS rather than the more legible original source).

If you do not want your deployed site to be indexed by search engines (for example if you are still developing your live site), or if you want to build a development version of your site for offline analysis, you can set your Hugo build environment to something else such as development (the default for local deploys with hugo server), test, or another environment name of your choice.

The simplest way to set this is by using the -e flag when specifying or running your hugo command, as in the following example:

hugo -e development

Deployment with Netlify

We recommend using Netlify as a particularly simple way to serve your site from your Git provider (GitHub, GitLab, or BitBucket), with continuous deployment, previews of the generated site when you or your users create pull requests against the doc repo, and more. Netlify is free to use for Open Source projects, with premium tiers if you require greater support.

Before deploying with Netlify, make sure that you’ve pushed your site source to your chosen GitHub (or other provider) repo, following any setup instructions in Using the theme.

Then follow the instructions in Host on Netlify to set up a Netlify account (if you don’t have one already) and authorize access to your GitHub or other Git provider account. Once you’re logged in:

  1. Click New site from Git.
  2. Click your chosen Git provider, then choose your site repo from your list of repos.
  3. In the Deploy settings page:
    1. For your Build command, specify cd themes/docsy && git submodule update -f --init && cd ../.. && hugo. You need to specify this rather than just hugo so that Netlify can use the theme’s submodules. If you don’t want your site to be indexed by search engines, you can add an environment flag to specify a non-production environment, as described in Build environments and indexing.
    2. Click Show advanced.
    3. In the Advanced build settings section, click New variable.
    4. Specify HUGO_VERSION as the Key for the new variable, and 0.53 or later as its Value.
  4. Click Deploy site.

Alternatively, you can follow the same instructions but specify your Deploy settings in a netlify.toml file in your repo rather than in the Deploy settings page. You can see an example of this in the Docsy theme repo (though note that the build command here is a little unusual because the Docsy user guide is inside the theme repo).

If you have an existing deployment you can view and update the relevant information by selecting the site from your list of sites in Netlify, then clicking Site settings - Build and deploy. Ensure that Ubuntu Xenial 16.04 is selected in the Build image selection section - if you’re creating a new deployment this is used by default. You need to use this image to run the extended version of Hugo.

5 - Examples

Some examples of Docsy in action!

One of the best ways to see what Docsy can do, and learn how to configure a site with it, is to see some real projects. In addition to our provided Docsy Example Project, there are several live sites already using the theme. Please add your own examples once you’ve got a production site up and running with Docsy!

Docsy theme examples

Example sites that have low to no customization:

Site Repo (if public)
This Docsy documentation site
“Goldydocs” - a Docsy example site
Navidrome Music Server

Customized Docsy examples

Example sites that include a moderate to high amount of customization:

Site Repo (if public)
Knative and
Apache Airflow
Docsy Just Docs
Thunderhead Engineering Product Support (private)

6 - Updating Docsy

Keeping the theme up to date.

We hope to continue to make improvements to the theme along with the Docsy community. If you have cloned the example site (or are otherwise using the theme as a submodule), you can update the Docsy theme yourself.

Updating Docsy means that your site will build using the latest version of Docsy at HEAD and include all the new commits or changes that have been merged since the point in time that you initially added the Docsy submodule, or last updated. Updating won’t affect any modifications that you made in your own project to override the Docsy look and feel, as your overrides don’t modify the theme itself. For details about what has changed in the theme, see the list of Docsy commits.

Depending on how you chose to use Docsy, follow the corresponding steps to update the theme:

Update a Docsy submodule

If you are using the Docsy theme as a submodule in your project (for example, if you’ve copied our example site), you update the submodule:

  1. Navigate to the root of your local project, then run:

     git submodule update --remote
  2. Add and then commit the change to your project:

     git add themes/
     git commit -m "Updating theme submodule"
  3. Push the commit to your project repo. For example, run:

     git push origin master

Update your Docsy clone

If you cloned the Docsy theme into the themes folder in your project, then you use the git pull command:

  1. Navigate to the themes directory in your local project:

     cd themes
  2. Ensure that origin is set to

     git remote -v
  3. Update your local clone:

     git pull origin master

If you have made any local changes to the cloned theme, you must manually resolve any merge conflicts.

7 - Best Practices

Optional guidance and recommendations about organizing, authoring, and managing your technical documentation.

Use this section to learn about some of the best practices around creating technical documentation with Docsy.

7.1 - Hugo Content Tips

Tips for authoring content for your Docsy-themed Hugo site.

Docsy is a theme for the Hugo static site generator. If you’re not already familiar with Hugo and, in particular, its version of Markdown, this page provides some useful tips and potential gotchas for adding and editing content for your site. Feel free to add your own!

Nested lists

Hugo currently uses the Blackfriday Markdown processor, which can be sensitive when it come to content that’s deeply nested in a list. In particular, be aware that this known issue can surface if or when you have multiple authors and other contributors who might mix ‘tabs’ and ‘spaces’ when indenting lists, or fail to indent properly.

An additional factor here is that because GitHub uses a different Markdown processor, GitHub markdown and the editor UI may render some nested lists properly, while Blackfriday might render that same content poorly. For example, the count in a numbered list might restart, or your nested content within a list is not indented (shows as a peer element instead of a nested child element). You may want to recommend in your contribution guidelines (as we do) that contributors preview their content with Hugo (or use Netlify’s preview feature for PRs if that’s your chosen deployment tool) to ensure their content renders correctly with Blackfriday.


By default, regular relative URLs in links are left unchanged by Hugo (they’re still relative links in your site’s generated HTML), hence some hardcoded relative links like [relative cross-link](../../peer-folder/ might behave unexpectedly compared to how they work on your local file system. You may find it helpful to use some of Hugo’s built-in link shortcodes to avoid broken links in your generated site. For example a {{< ref "" >}} link in Hugo will actually find and automatically link to your file named

Note, however, that ref and relref links don’t work with _index or index files (for example, this site’s content landing page): you’ll need to use regular Markdown links to section landing or other index pages. Specify these links relative to the site’s root URL, for example: /docs/adding-content/.

Learn more about linking.

7.2 - Organizing Your Content

Optional guidance and recommendations on how to organize your documentation site.

If you have a look at our Example Site, you’ll see that we’ve organized the Documentation section into a number of subsections, each with some recommendations about what you might put in that section.

Do I need to use this structure?

Absolutely not! The site structure in the Example Site was created to meet the needs of large docsets for large products with lots of features, potential tasks, and reference elements. For a simpler docset (like this one!), it’s fine to just structure your docs around specific features that your users need to know about. Even for larger documentation sets, you may find that the structure isn’t useful “as is”, or that you don’t need to use all the section types.

We do recommend that (as we’ve done here) you provide at least:

  • An Overview of the product (either on the docs landing page or a separate Overview page) that tells the user why they should be interested in your project.
  • A Getting Started page.
  • Some Examples.

You may also want to create some tasks/how-tos for your project’s features. Feel free to copy this Docsy user guide site or even just the docs section instead if you like this simpler structure better.

Learn more about how Hugo and Docsy use folders and other files to organize your site.

Why this structure?

We based the Example Site structure on our own experiences creating (and using) large documentation sets for different types of project and on user research carried out on some of our bigger sites. In user studies we saw that users cared most about and immediately looked for a Get Started or Getting Started section (so they could, well, get started), and some examples to explore and copy, so we made those into prominent top-level doc sections in our site. Users also wanted to find “recipes” that they could easily look up to perform specific tasks and put together to create their own applications or projects, so we suggest that you add this kind of content as Tasks. Other content types such as conceptual docs, reference docs, and end-to-end tutorials are less important for all doc sets, particularly for smaller projects. We emphasize in our Example Site that these sections are optional.

We hope to improve the Example Site structure further as we learn more about how users interact with technical documentation, particularly for Open Source projects.

Writing style guide

This guide and the example site just address how to organize your documentation content into pages and sections. For some guidance on how to organize and write the content in each page, we recommend the Google Developer Documentation Style Guide, particularly the Style Guide Highlights.

8 - Contribution Guidelines

How to contribute to Docsy

Docsy is an open source project and we love getting patches and contributions to make Docsy and its docs even better.

Contributing to Docsy

The Docsy theme itself lives in

Contributor License Agreement

Contributions to this project must be accompanied by a Contributor License Agreement. You (or your employer) retain the copyright to your contribution; this simply gives us permission to use and redistribute your contributions as part of the project. Head over to to see your current agreements on file or to sign a new one.

You generally only need to submit a CLA once, so if you’ve already submitted one (even if it was for a different project), you probably don’t need to do it again.

Code reviews

All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult GitHub Help for more information on using pull requests.

Previewing your changes

As Docsy is a theme rather than a site, you can’t serve the theme directly to check your changes work. Instead use your updated local theme in a local copy of the Docsy example site (copy or make your changes in the themes/docsy directory) and preview from there. Alternatively, clone the Docsy theme repo and test your changes in a local copy of this site, as described below.

Community guidelines

This project follows Google’s Open Source Community Guidelines.

Creating issues

Alternatively, if there’s something you’d like to see in Docsy (or if you’ve found something that isn’t working the way you’d expect), but you’re not sure how to fix it yourself, please create an issue.

Contributing to these docs

This user guide is, like our example site, a Docsy site that uses the Hugo static site generator. We welcome updates to the docs!

We use Netlify to manage the deployment of the site and provide previews of doc updates. The instructions here assume you’re familiar with basic GitHub workflows.

Quick start with Netlify

  1. Fork the Docsy repo on GitHub: this site’s files live in the userguide subdirectory.
  2. Make your changes and send a pull request (PR).
  3. If you’re not yet ready for a review, add “WIP” to the PR name to indicate it’s a work in progress. (Don’t add the Hugo property “draft = true” to the page front matter, because that prevents the auto-deployment of the content preview described in the next point.)
  4. Wait for the automated PR workflow to do some checks. When it’s ready, you should see a comment like this: deploy/netlify — Deploy preview ready!
  5. Click Details to the right of “Deploy preview ready” to see a preview of your updates.
  6. Continue updating your doc and pushing your changes until you’re happy with the content.
  7. When you’re ready for a review, add a comment to the PR, and remove any “WIP” markers.

Updating a single page

If you’ve just spotted something you’d like to change while using the docs, Docsy has a shortcut for you:

  1. Click Edit this page in the top right hand corner of the page.
  2. If you don’t already have an up to date fork of the project repo, you are prompted to get one - click Fork this repository and propose changes or Update your Fork to get an up to date version of the project to edit. The appropriate page in your fork is displayed in edit mode.
  3. Follow the rest of the Quick start with Netlify process above to make and preview your changes.

Previewing your changes locally

If you want to run your own local Hugo server to preview your changes as you work:

  1. Follow the instructions in Getting started to install Hugo and any other tools you need.

  2. Fork the Docsy repo into your own project, then create a local copy using git clone. Don’t forget to use --recurse-submodules or you won’t pull down some of the code you need to generate a working site.

    git clone --recurse-submodules --depth 1
  3. Change to the userguide directory and run the following Hugo command to build the site and start the Hugo server. Note that you need the themesDir flag because the site files are inside the theme repo.

    cd userguide
    hugo server --themesDir ../..

    By default your site will be available at http://localhost:1313/. Now that you’re serving your site locally, Hugo will watch for changes to the content and automatically refresh your site.

  4. Continue with the usual GitHub workflow to edit files, commit them, push the changes up to your fork, and create a pull request.

Creating an issue

If there’s something you’d like to see in the docs, but you’re not sure how to fix it yourself, please create an issue in this repository. You can also create an issue about a specific page by clicking the Create Issue button in the top right hand corner of the page.