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.
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 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).
Learn how to get started with Docsy, including the available options for installing and using the Docsy theme.
As you saw in our introduction, Docsy is a Hugo theme, which means that if you want to use Docsy, you need to set up your website source so that the Hugo static site generator can find and use the Docsy theme files when building your site. The simplest way to do this is to copy and edit our example site, though we also provide instructions for adding the Docsy theme manually to new or existing sites.
If you want to build and test your site locally you also need to be able to run Hugo itself, either by installing it and any other required dependencies, or by using our provided Docker container.
This page describes Docsy’s installation options and helps you choose the appropriate setup guide to get started.
Installation options
Hugo offers multiple options for using themes, all of which are supported by Docsy.
Adding the theme as a Hugo Module: Hugo Modules are the simplest and latest way to use Hugo themes. Hugo uses the modules mechanism to pull in the theme files from the main Docsy repo at your chosen revision, and it’s easy to keep the theme up to date in your site. Our example site uses Docsy as a Hugo Module.
Adding the theme as a Git submodule: Adding the theme as a Git submodule also lets Hugo use the theme files from their own repo, though is more complicated to maintain than the Hugo modules approach. This is the approach used in older versions of the Docsy example site and is still supported.
Cloning the theme files: If you don’t want Hugo to have to get the theme files from an external repo (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 files directly into your site source.
Migration and backward compatibility
If you have an existing site that uses Docsy as a Git submodule, and you would like to update it to use Hugo Modules, follow our migration guide. If you’re not ready to migrate yet, don’t worry! Your site will continue to work as usual.
Setup guides
Follow the setup guide for your chosen approach. If you’re new to Docsy and not sure which guide to follow, we recommend following the Use Docsy as a Hugo Module guide as a simple and easily maintained option.
1.1 - Use Docsy as a Hugo Module
Learn how to get started with Docsy by using the theme as a Hugo Module.
Hugo modules are the simplest and latest way to use Hugo themes like Docsy when building a website. Hugo uses the modules mechanism to pull in the theme files from the main Docsy repo at your chosen revision, and it’s easy to keep the theme up to date in your site. Our example site uses Docsy as a Hugo module.
To find out about other setup approaches, see our Get started overview. If you want to migrate an existing Docsy site to use Hugo Modules, see our migration guide.
Setup options with Hugo Modules
To use Docsy as a Hugo Module, 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 Hugo Module.
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.
If you’re a beginner, we recommend that you get started by copying our example site. If you’re already familiar with Hugo or want a very different site structure, you can follow our guide to start a site from scratch, which gives you maximum flexibility at the cost of higher implementation effort. In both cases you need to follow our prerequisites guide to make sure that you have installed Hugo and all necessary dependencies.
1.1.1 - Before you begin
Prerequisites for building a site with Docsy as a Hugo Module.
This page describes the prerequisites for building a site that uses Docsy as a Hugo Module.
Install Hugo
You need a recent extended version (version 0.110.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 gohugo.io.
If you’ve already installed Hugo, check your version:
hugo version
If the result is v0.109.0 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:
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:
Hugo’s commands for module management require that the Go programming language is installed on your system. Check whether go is already installed:
$ go version
go version go1.21.6
Ensure that you are using version 1.12 or higher.
If the go language is not installed on your system yet or if you need to upgrade, go to the download area of the Go website, choose the installer for your system architecture and execute it. Afterwards, check for a successful installation.
Install Git VCS client
Hugo’s commands for module management require that the git client is installed on your system. Check whether git is already present in your system:
$ git version
git version 2.43.0
If no git client is installed on your system yet, go to the Git website, download the installer for your system architecture and execute it. Afterwards, check for a successful installation.
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:
Note that versions of PostCSS later than 5.0.1 will not load autoprefixer if installed globally, you must use a local install.
Install/Upgrade Node.js
To ensure you can properly build your site beyond executing hugo server, you must have the latest long term support (LTS) Version of Node.js. If you do not have the latest LTS version, you may see the one of following errors:
Error: Error building site: POSTCSS: failed to transform "scss/main.css" (text/css): Unexpected identifier
#OR
/home/user/repos/my-new-site/themes/docsy/node_modules/hugo-extended/postinstall.js:1
import install from "./lib/install.js";
^^^^^^^
SyntaxError: Unexpected identifier
at Module._compile (internal/modules/cjs/loader.js:723:23)
at Object.Module._extensions..js (internal/modules/cjs/loader.js:789:10)
at Module.load (internal/modules/cjs/loader.js:653:32)
at tryModuleLoad (internal/modules/cjs/loader.js:593:12)
at Function.Module._load (internal/modules/cjs/loader.js:585:3)
at Function.Module.runMain (internal/modules/cjs/loader.js:831:12)
at startup (internal/bootstrap/node.js:283:19)
at bootstrapNodeJSCore (internal/bootstrap/node.js:623:3)
You can check your current Node.js version by running node -v. If you need to install a new version, see the following instructions:
1.1.2 - Create a new site: start with a prepopulated site
Create a new Hugo site by using a clone of the Docsy example site as your starting point.
The simplest way to create a new Docsy site is to use the source of the Docsy example site as starting point. 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 automatically pulls in the Docsy theme as a Hugo Module, so it’s easy to keep up to date.
If you prefer to create a site from scratch, follow the instructions in Start a site from scratch.
TL;DR: Setup for the impatient expert
At your Unix shell or Windows command line, run the following command:
git clone --depth 1 --branch v0.11.0 https://github.com/google/docsy-example.git my-new-site
cd my-new-site
hugo server
The Example Site gives you a good starting point for building your docs site and is
pre-configured to automatically pull in the Docsy theme as a Hugo Module.
There are two different routes to get a local clone of the example site:
If you want to create a local copy only, choose option 1.
If you have a GitHub account and want to create a GitHub repo for your site go for option 2.
Option 1: Using the command line (local copy only)
If you want to use a remote repository other than GitHub (such as GitLab, BitBucket, AWS CodeCommit, Gitea) or if you don’t want a remote repo at all, simply make a local working copy of the example site directly using git clone. As last parameter, give your chosen local repo name (here: my-new-site):
Use the dropdown for switching branches/tags to change to the latest released tag v0.11.0.
Click the button Use this template and select the option Create a new repository from the dropdown.
Chose a name for your new repository (e.g. my-new-site) and type it in the Repository name field. You can also add an optional Description.
Click Create repository from template to create your new repository. Congratulations, you just created your remote Github clone which now serves as starting point for your own site!
Make a local copy of your newly created GitHub repository by using git clone, giving your repo’s web URL as last parameter.
Depending on your environment you may need to tweak the module top level settings inside your hugo.toml slightly, for example by adding a proxy to use when downloading remote modules.
You can find details of what these configuration settings do in the Hugo modules documentation.
Now you can make local edits and test your copied site locally with Hugo.
Preview your site
To build and preview your site locally, switch to the root of your cloned project and use hugo’s server command:
cd my-new-site
hugo server
Preview your site in your browser at: http://localhost:1313.
Thanks to Hugo’s live preview, you can immediately see the effect of changes that you are making to the source files of your local repo.
Use Ctrl + c to stop the Hugo server whenever you like.
See the known issues on MacOS.
1.1.3 - Create a new site: Start a new site from scratch
Create a new Hugo site from scratch with Docsy as a Hugo Module
The simplest approach to creating a Docsy site is copying our example site. However, if you’re an experienced Hugo user or the site structure of our example site doesn’t meet your needs, you may prefer to create a new site from scratch. With this option, you’ll get Docsy look and feel, navigation, and other features, but you’ll need to specify your own site structure.
These instructions give you a minimum file structure for your site project only, so that you build and extend your actual site step by step. The first step is adding the Docsy theme as a Hugo Module to your site. If needed, you can easily update the module to the latest revision from the Docsy GitHub repo.
TL;DR: Setup for the impatient expert
At your command prompt, run the following:
hugo new site my-new-site
cd my-new-site
hugo mod init github.com/me/my-new-site
hugo mod get github.com/google/docsy@v0.11.0
cat >> hugo.toml <<EOL
[module]
proxy = "direct"
[[module.imports]]
path = "github.com/google/docsy"
EOLhugo server
hugo new site my-new-site
cd my-new-site
hugo mod init github.com/me/my-new-site
hugo mod get github.com/google/docsy@v0.11.0
(echo [module]^
proxy = "direct"^
[[module.imports]]^
path = "github.com/google/docsy")>> hugo.toml
hugo server
Specifying the Docsy theme as Hugo Module for your minimal site gives you all the theme-y goodness, but you’ll need to specify your own site structure.
Create your new skeleton 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 my-new-site
cd my-new-site
This will create a minimal site structure, containing the folders archetypes, content, data, layouts, static, and themes and a configuration file (default: hugo.toml).
Tip
In Hugo 0.110.0 the default config base filename was changed to hugo.toml.
If you are using hugo 0.110 or above, consider renaming your config.toml to hugo.toml!
Import the Docsy theme module as a dependency of your site
Only sites that are Hugo Modules themselves can import other modules. To turn your site into a Hugo Module, run the following commands in your newly created site directory:
hugo mod init github.com/me/my-new-site
This creates two new files, go.mod for the module definitions and go.sum which holds the checksums for module verification.
Next declare the Docsy theme module as a dependency for your site.
hugo mod get github.com/google/docsy@v0.11.0
This command adds the docsy theme module to your definition file go.mod.
Add theme module configuration settings
Add the settings in the following snippet at the end of your site’s configuration file (default: hugo.toml) and save the file.
[module]proxy="direct"# uncomment line below for temporary local development of module# replacements = "github.com/google/docsy -> ../../docsy"[module.hugoVersion]extended=truemin="0.73.0"[[module.imports]]path="github.com/google/docsy"disable=false
You can find details of what these configuration settings do in the Hugo modules documentation.
Depending on your environment you may need to tweak them slightly, for example by adding a proxy to use when downloading remote modules.
Preview your site
To build and preview your site locally:
hugo server
By default, your site will be available at http://localhost:1313. When encountering problems, have a look at the known issues on MacOS.
You may get Hugo errors for missing parameters and values when you try to build your site. This is usually because you’re missing default values for some configuration settings that Docsy uses - once you add them your site should build correctly. You can find out how to add configuration in Basic site configuration - we recommend copying the example site configuration even if you’re creating a site from scratch as it provides defaults for many required configuration parameters.
Create a new Docsy site with Docsy using Git or NPM
If you don’t want to use
Docsy as a Hugo Module (for example if you
do not want to install Go) but still don’t want to copy the theme files into
your own repo, you can use Docsy as a
Git submodule. Using
submodules also lets Hugo use the theme files from Docsy repo, though is more
complicated to maintain than the Hugo Modules approach. This is the approach
used in older versions of the Docsy example site, and is still supported. If you
are using Docsy as a submodule but would like to migrate to Hugo Modules, see
our migration guide.
Alternatively if you don’t want Hugo to have to get the theme files from an
external repo (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 files directly into your
site source.
This guide provides instructions for all of these options, along with common
prerequisites.
Prerequisites
Install Hugo
You need a
recent extended version (we
recommend version 0.73.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 gohugo.io.
If you’ve already installed Hugo, check your version:
hugo version
If the result is v0.73 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:
You can install Hugo as an NPM module using
hugo-extended. To install the
extended version of Hugo:
npm install hugo-extended --save-dev
Node: Get the latest LTS release
If you have Node installed already, check your version of Node. For example:
node -v
Install or upgrade your version of Node to the active LTS release. We recommend
using nvm to manage your Node installation (Linux command shown):
nvm install --lts
Install PostCSS
To build or update your site’s CSS resources, you’ll also need
PostCSS. Install it using the Node package manager,
npm.
IMPORTANT: Check your Node version
The PostCSS package installed by some older versions of Node is incompatible
with Docsy. Check your version of Node against the active LTS release and
upgrade, if necessary. For details, see Node: Get the latest LTS release.
From your project root, run this command:
npm install --save-dev autoprefixer postcss-cli
Option 1: Docsy as a Git submodule
For a new site
To create a new site and add the Docsy theme as a Git submodule, run the
following commands:
As of Hugo 0.110.0, the default config base
filename was changed to hugo.* from config.*. If you are using hugo
0.110 or above, consider renaming your config.* to hugo.*.
(Optional but recommended) To avoid having to repeat the previous step every
time you update Docsy, consider adding NPM scripts like the following to
your project’s package.json file:
{"...":"...","scripts":{"get:submodule":"git submodule update --init --depth 1","_prepare:docsy":"cd themes/docsy && npm install","prepare":"npm run get:submodule && npm run _prepare:docsy","...":"..."},"...":"..."}
Every time you run npm install from your project root, the prepare
script will fetch the latest version of Docsy and its dependencies.
From this point on, build and serve your site using the usual Hugo commands, for
example:
hugo serve
Option 2: Clone the Docsy theme
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’s themes subdirectory.
To clone Docsy at v0.11.0 into your project’s theme folder, run
the following commands from your project’s root directory:
cd themes
git clone -b v0.11.0 https://github.com/google/docsy
cd docsy
npm install
To work from the development version of Docsy (not recommended unless, for
example, you plan to upstream changes to Docsy), omit the
-b v0.11.0 argument from the clone command above.
Then consider setting up an NPM prepare script, as documented in Option 1.
Build or serve your new site using the usual Hugo commands, specifying the
path to the Docsy theme files. For example, build your site as follows:
$ hugo
Start building sites …
...
Error: failed to load modules
If Hugo reports the following error when building your site (#2116):
Error: failed to load modules: module "github.com/FortAwesome/Font-Awesome" not found in ".../myproject/node_modules/github.com/FortAwesome/Font-Awesome" ...
Then run the following command and try again:
npm rebuild
As an alternative to specifying a themesDir, on some platforms, you can
instead create a symbolic link to the Docsy theme directory as follows (Linux
commands shown, executed from the site root folder):
You may get Hugo errors for missing parameters and values when you try to build
your site. This is usually because you’re missing default values for some
configuration settings that Docsy uses - once you add them your site should
build correctly. You can find out how to add configuration in
Basic site configuration - we
recommend copying the example site configuration even if you’re creating a site
from scratch as it provides defaults for many required configuration parameters.
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.
Build the docker image:
docker-compose build
Run the built image:
docker-compose up
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.
Cleanup
To cleanup your system and delete the container image follow the next steps.
Site-wide configuration details and parameters are defined in your project’s configuration file (hugo.toml or config.toml). 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 hugo.toml in the example project for how to add this information. We recommend copying this hugo.toml and editing it even if you’re just using the theme and not copying the entire Docsy example site, as it includes default values for many parameters that you need to set for your site to build correctly.
You may want to remove or customize some defaults of the copied hugo.toml file straight away:
Internationalization
The copied hugo.toml file defines 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 hugo.toml:
[languages.no]languageName="Norsk"contentDir="content/no"[languages.no.params]title="Goldydocs"description="Docsy er operativsystem for skyen"time_format_default="02.01.2006"time_format_blog="02.01.2006"[languages.fa]languageName="فارسی"contentDir="content/fa"[languages.fa.params]title="اسناد گلدی"description="یک نمونه برای پوسته داکسی"time_format_default="2006.01.02"time_format_blog="2006.01.02"
Search
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 = "..."
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 127.0.0.1:1313: socket: too many open files
POSTCSS v8 and later:
fatal error: pipe failed
Workaround
To temporarily allow more open files:
View your current settings by running:
sudo launchctl limit maxfiles
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.
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.
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.
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.
It also provides a default “landing page” type of template with the site header and footer, but no left nav, that you can use for any other section. In this site and our example site it’s used for the site home page and the About page.
Each top-level section in your site corresponds to a directory in your site content root. Hugo automatically applies the appropriate template for that section, depending on which folder the content is in. For example, this page is in the docs subdirectory of the site’s content root directory content/en/, so Hugo automatically applies the docs template. You can override this by explicitly specifying a template or content type for a particular page.
If you’ve copied the example site, you already have appropriately named top-level section directories for using Docsy’s templates, each with an index page ( _index.md or index.html) page for users to land on. These top-level sections also appear in the example site’s top-level menu.
Custom sections
If you’ve copied the example site and don’t want to use one of the provided content sections, just delete the appropriate content subdirectory. Similarly, if you want to add a top-level section, just add a new subdirectory, though you’ll need to specify the layout or content type explicitly in the frontmatter of each page if you want to use any existing Docsy template other than the default one. For example, if you create a new directory content/en/amazing and want one or more pages in that custom section to use Docsy’s docs template, you add type: docs to the frontmatter of each page:
+++title="My amazing new section"weight=1type="docs"description='''
A special section with a docs layout.
'''+++
---title:"My amazing new section"weight:1type:docsdescription:> A special section with a docs layout.---
{"title":"My amazing new section","weight":1,"type":"docs","description":"A special section with a docs layout.\n"}
Alternatively, create your own page template for your new section in your project’s layouts directory based on one of the existing templates.
You can find out much more about how Hugo page layouts work in Hugo Templates. The rest of this page tells you about how to add content and use each of Docsy’s templates.
Alternative site structure
As noted above, by default your site has a home page (using the _default layout), a docs section under /docs/, a blog section under /blog/ and a community section under /community/. The type of each section (which determines the layout it uses) matches its directory name.
In some cases, you may want to have a different directory structure, but still make use of Docsy’s layouts. A common example is for a “docs site”, where most of the pages (including the home page) use the docs layout, or perhaps you’d rather have a /news/ directory treated with the blog layout.
Since Hugo 0.76, this has become practical without copying layouts to your site, or having to specify type: blog on every single page by making use of target specific cascading front matter.
For example, for the /news/ section, you can specify the following front matter in the index page which will change the type of the section and everything below it to “blog”:
If you want to create a “docs” site, specifying something like the following in the top level _index.md will set all top level sections to be treated as “docs”, except for “news”:
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=1description='''
Add different types of content to your Docsy site.
'''+++
---title:"Adding Content"linkTitle:"Adding Content"weight:1description:> Add different types of content to your Docsy site.---
{"title":"Adding Content","linkTitle":"Adding Content","weight":1,"description":"Add different types of content to your Docsy site.\n"}
The minimum frontmatter you need to provide is a title: everything else is up to you! However, if you leave out the page weight, your navigation may get a little disorganized. You may also want to include description since Docsy uses that to generate the meta description tag used by search engines. See Search Engine Optimization (SEO) meta tags for details.
Page contents and markup
By default you create pages in a Docsy site as simple Markdown or HTML files with page frontmatter, as described above.
As of version 0.100, Goldmark is the only Markdown parser supported by Hugo.
Tip
If you’ve been using versions of Hugo before 0.60 that use BlackFriday as its Markdown parser, you may need to make some small changes to your site to work with the current Goldmark Markdown parser. In particular, if you cloned an earlier version of our example site, add the following to your hugo.toml/hugo.yaml/hugo.json to allow Goldmark to render raw HTML as well as Markdown:
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.
Note
Hugo also supports adding content using other markups using external parsers as helpers. For example, you can add content in RST using rst2html as an external parser (though be aware this does not support all flavors of RST, such as Sphinx RST). Similarly, you can use asciidoctor to parse Asciidoc files, or pandoc for other formats.
External parsers may not be suitable for use with all deployment options, as you’ll need to install the external parser and run Hugo yourself to generate your site (so, for example, you won’t be able to use Netlify’s continuous deployment feature). In addition, adding an external parser may cause performance issues building larger sites.
Working with links
Hugo lets you specify links using normal Markdown syntax, though remember that you need to specify links relative to your site’s root URL, and that relative URLs are left unchanged by Hugo in your site’s generated HTML.
Alternatively you can use Hugo’s helper ref and relref shortcodes for creating internal links that resolve to the correct URL. However, be aware this means your links will not appear as links at all if a user views your page outside your generated site, for example using the rendered Markdown feature in GitHub’s web UI.
You can find (or add!) tips and gotchas for working with Hugo links in Hugo Tips.
Content style
We don’t mandate any particular style for your page contents. However, if you’d like some guidance on how to write and format clear, concise technical documentation, we recommend the Google Developer Documentation Style Guide, particularly the Style Guide Highlights.
Page bundles
You can create site pages as standalone files in their section or subsection directory, or as folders where the content is in the folder’s index page. Creating a folder for your page lets you bundle images and other resources together with the content.
You can see examples of both approaches in this and our example site. For example, the source for this page is just a standalone file /content/en/docs/adding-content.md. However the source for Docsy Shortcodes in this site lives in /content/en/docs/adding-content/shortcodes/index.md, with the image resource used by the page in the same /shortcodes/ directory. In Hugo terminology, this is called a leaf bundle because it’s a folder containing all the data for a single site page without any child pages (and uses index.md without an underscore).
You can find out much more about managing resources with Hugo bundles in Page Bundles.
Adding docs and blog posts
The template you’ll probably use most often is the docs template (as used in this page) or the very similar blog template. Both these templates include:
a left nav
GitHub links (populated from your site config) for readers to edit the page or create issues
a page menu
as well as the common header and footer used by all your site’s pages. Which template is applied depends on whether you’ve added the content to the blog or docs content directory. You can find out more about how the nav and page menu are created in Navigation and Search.
Organizing your documentation
While Docsy’s top-level sections let you create site sections for different types of content, you may also want to organize your docs content within your docs section. For example, this site’s docs section directory has multiple subdirectories for Getting Started, Content and Customization, and so on. Each subdirectory has an _index.md (it could also be an _index.html), which acts as a section index page and tells Hugo that the relevant directory is a subsection of your docs.
Docsy’s docs layout gives you a left nav pane with an autogenerated nested menu based on your docs file structure. Each standalone page or subsection _index.md or _index.html page in the docs/ directory gets a top level menu item, using the link name and weight metadata from the page or index.
To add docs to a subsection, just add your page files to the relevant subdirectory. Any pages that you add to a subsection in addition to the subsection index page will appear in a submenu (look to the left to see one in action!), again ordered by page weight. Find out more about adding Docsy’s navigation metadata in Navigation and Search
If you’ve copied the example site, you’ll already have some suggested subdirectories in your docs directory, with guidance for what types of content to put in them and some example Markdown pages. You can find out more about organizing your content with Docsy in Organizing Your Content.
Docs section landing pages
By default a docs section landing page (the _index.md or _index.html in the section directory) uses a layout that adds a formatted list of links to the pages in the section, with their frontmatter descriptions. The Content and Customization landing page in this site is a good example.
To display a simple bulleted list of links to the section’s pages instead, specify simple_list: true in the landing page’s frontmatter:
+++title="Simple List Page"simple_list=trueweight=20+++
---title:"Simple List Page"simple_list:trueweight:20---
{"title":"Simple List Page","simple_list":true,"weight":20}
To display no links at all, specify no_list: true in the landing page’s frontmatter:
+++title="No List Page"no_list=trueweight=20+++
---title:"No List Page"no_list:trueweight:20---
{"title":"No List Page","no_list":true,"weight":20}
Organizing your blog posts
Docsy’s blog layout also gives you a left nav menu (like the docs layout), and a list-type index page for your blog that’s applied to /blog/_index.md and automatically displays snippets of all your recent posts in reverse chronological order.
To create different blog categories to organize your posts, create subfolders in blog/. For instance, in our example site we have news and releases. Each category needs to have its own _index.md or _index.html landing page file specifying the category title for it to appear properly in the left nav and top-level blog landing page. Here’s the index page for releases:
To add author and date information to blog posts, add them to the page frontmatter:
+++date=2018-10-06T00:00:00.000Ztitle="Easy documentation with Docsy"linkTitle="Announcing Docsy"description="The Docsy Hugo theme lets project maintainers and contributors focus on content, not on reinventing a website infrastructure from scratch"author="Riona MacNamara"[[resources]]src="**.{png,jpg}"title="Image #:counter"[resources.params]byline="Photo: Riona MacNamara / CC-BY-CA"+++
---date:2018-10-06title:"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 MacNamararesources:- src:"**.{png,jpg}"title:"Image #:counter"params:byline:"Photo: Riona MacNamara / CC-BY-CA"---
{"date":"2018-10-06T00:00:00.000Z","title":"Easy documentation with Docsy","linkTitle":"Announcing Docsy","description":"The Docsy Hugo theme lets project maintainers and contributors focus on content, not on reinventing a website infrastructure from scratch","author":"Riona MacNamara","resources":[{"src":"**.{png,jpg}","title":"Image #:counter","params":{"byline":"Photo: Riona MacNamara / CC-BY-CA"}}]}
If you’ve copied the example site and you don’t want a blog section, or want to link to an external blog instead, just delete the blog subdirectory.
Working with top-level landing pages.
Docsy’s default page template has no left nav and is useful for creating a home page for your site or other “landing” type pages.
Customizing the example site pages
If you’ve copied the example site, you already have a simple site landing page in content/en/_index.html. This is made up of Docsy’s provided Hugo shortcode page blocks.
To customize the large landing image, which is in a cover block, replace the content/en/featured-background.jpg file in your project with your own image (it can be called whatever you like as long as it has background in the file name). You can remove or add as many blocks as you like, as well as adding your own custom content.
The example site also has an About page in content/en/about/_index.html using the same Docsy template. Again, this is made up of page blocks, including another background image in content/en/about/featured-background.jpg. As with the site landing page, you can replace the image, remove or add blocks, or just add your own content.
Building your own landing pages
If you’ve just used the theme, you can still use all Docsy’s provided page blocks (or any other content you want) to build your own landing pages in the same file locations.
Adding a community page
The community landing page template has boilerplate content that’s automatically filled in with the project name and community links specified in hugo.toml/hugo.yaml/hugo.json, providing your users with quick links to resources that help them get involved in your project. The same links are also added by default to your site footer.
[params.links]# End user relevant links. These will show up on left side of footer and in the community page if you have one.[[params.links.user]]name="User mailing list"url="https://example.org/mail"icon="fa fa-envelope"desc="Discussion and help from your fellow users"[[params.links.user]]name="Twitter"url="https://example.org/twitter"icon="fab fa-x-twitter"desc="Follow us on Twitter to get the latest news!"[[params.links.user]]name="Stack Overflow"url="https://example.org/stack"icon="fab fa-stack-overflow"desc="Practical questions and curated answers"# Developer relevant links. These will show up on right side of footer and in the community page if you have one.[[params.links.developer]]name="GitHub"url="https://github.com/google/docsy"icon="fab fa-github"desc="Development takes place here!"[[params.links.developer]]name="Slack"url="https://example.org/slack"icon="fab fa-slack"desc="Chat with other project developers"[[params.links.developer]]name="Developer mailing list"url="https://example.org/mail"icon="fa fa-envelope"desc="Discuss development issues around the project"
params:links:user:- name:User mailing listurl:'https://example.org/mail'icon:fa fa-envelopedesc:Discussion and help from your fellow users- name:Twitterurl:'https://example.org/twitter'icon:fab fa-x-twitterdesc:Follow us on Twitter to get the latest news!- name:Stack Overflowurl:'https://example.org/stack'icon:fab fa-stack-overflowdesc:Practical questions and curated answersdeveloper:- name:GitHuburl:'https://github.com/google/docsy'icon:fab fa-githubdesc:Development takes place here!- name:Slackurl:'https://example.org/slack'icon:fab fa-slackdesc:Chat with other project developers- name:Developer mailing listurl:'https://example.org/mail'icon:fa fa-envelopedesc:Discuss development issues around the project
{"params":{"links":{"user":[{"name":"User mailing list","url":"https://example.org/mail","icon":"fa fa-envelope","desc":"Discussion and help from your fellow users"},{"name":"Twitter","url":"https://example.org/twitter","icon":"fa-brands fa-x-twitter","desc":"Follow us on Twitter to get the latest news!"},{"name":"Stack Overflow","url":"https://example.org/stack","icon":"fa-brands fa-stack-overflow","desc":"Practical questions and curated answers"}],"developer":[{"name":"GitHub","url":"https://github.com/google/docsy","icon":"fa-brands fa-github","desc":"Development takes place here!"},{"name":"Slack","url":"https://example.org/slack","icon":"fa-brands fa-slack","desc":"Chat with other project developers"},{"name":"Developer mailing list","url":"https://example.org/mail","icon":"fa fa-envelope","desc":"Discuss development issues around the project"}]}}}
If you’re creating your own site and want to add a page using this template, add a /community/_index.md file in your content root directory. If you’ve copied the example site and don’t want a community page, just delete the /content/en/community/ directory in your project repo.
By default, Docsy layouts assume that your project’s contributing page is found
at <baseURL>/docs/contribution-guidelines. To specify another URL, add it to
the front matter of /community/_index.md as illustrated next. The URL can be
an external URL or a local path:
params:contributingUrl:docs/contributing/
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.
To disable all RSS feeds, add the following to your
hugo.toml/hugo.yaml/hugo.json:
disableKinds=["RSS"]
disableKinds:[RSS]
{"disableKinds":["RSS"]}
Note
If you have enabled our print feature or otherwise specified section-level output formats in hugo.toml/hugo.yaml/hugo.json, make sure that "RSS" is listed as an output format, otherwise you won’t get section-level RSS feeds (and your blog section won’t get a nice orange RSS button). Your hugo.toml/hugo.yaml/hugo.json specification overrides the Hugo default output formats for sections, which are HTML and RSS.
[outputs]section=["HTML","RSS","print"]
outputs:section:- HTML- RSS- print
{"outputs":{"section":["HTML","RSS","print"]}}
Sitemap
Hugo creates a sitemap.xml file for your generated site by default: for example, here’s the sitemap for this site.
You can configure the frequency with which your sitemap is updated, your sitemap filename, and the default page priority in your hugo.toml/hugo.yaml/hugo.json:
To override any of these values for a given page, specify it in page frontmatter:
+++title="Adding Content"linkTitle="Adding Content"weight=1description='''
Add different types of content to your Docsy site.
'''[sitemap]priority=1+++
---title:"Adding Content"linkTitle:"Adding Content"weight:1description:> Add different types of content to your Docsy site.sitemap:priority:1.0---
{"title":"Adding Content","linkTitle":"Adding Content","weight":1,"description":"Add different types of content to your Docsy site.\n","sitemap":{"priority":1}}
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
5 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 the
following Docsy placeholder files (note the _project*.scss suffixes) and
place them inside your project’s assets/scss/ folder:
Use these files to add project-specific definitions of theme variables as well
as any additional Bootstrap variables you want to set or override. For
details, including an explanation of which file to use, see
Site colors.
_styles_project.scss is where you can add your own custom SCSS styles,
including overriding any of the styles in Docsy’s theme SCSS files.
Tip
PostCSS (autoprefixing of CSS browser-prefixes) is not enabled when running in
server mode (it is a little slow), so Chrome is the recommended choice for
development.
Colors and color themes
Site colors
To customize your site’s colors, add SCSS variable overrides to
assets/scss/_variables_project.scss. For example, you can set the primary
and secondary site colors as follows:
$primary:#390040;$secondary:#a23b72;
Docsy has Bootstrap features such as gradient backgrounds
($enable-gradients) and shadows ($enable-shadows) enabled by default. These
can also be toggled in your project variables file by setting the variables to
false.
To add colors to or modify Bootstrap’s color maps, use assets/scss/_variables_project_after_bs.scss.
For example:
Docsy 0.10.0 supports light and dark mode color themes. To allow your website users
to choose light/dark modes, enable the Docsy light/dark menu or create
your own custom theme selector.
If your site uses Chroma for code highlighting, there are extra steps required
so that code-block styles are compatible with light/dark mode:
Ensure that markup.highlight.noClasses is false in your project config.
For details about this option, see Generate syntax highlighter CSS.
Light/dark color themes, only affect documentation pages, and white blocks shortcodes.
Fonts
The theme uses Open Sans as its
primary font. To disable Google Fonts and use a system font, set this SCSS
variable in assets/scss/_variables_project.scss:
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:
As of Hugo 0.60+, you can choose from a range of code block highlight and color
styles using Chroma. These styles are
applied to your fenced code blocks. For details about code highlighting in Hugo
using Chroma, see Syntax Highlighting.
Chroma style configuration
Hugo’s default Chroma style is monokai. To use another style, such as tango,
add the following to your project configuration:
By default, highlighting is not applied to code blocks without a specified
language. If you would like code highlighting to apply to all code blocks,
even without a language, set markup.highlight.guessSyntax to true in your
project’s configuration file.
Copy to clipboard
If you are using a Docsy 0.6.0 or later, code blocks show a “Copy to clipboard”
button in the top right-hand corner. To disable this functionality, set
disable_click2copy_chroma to true in your configuration file:
Code highlighting with Prism
Optionally, you can enable Prism syntax highlighting in your
hugo.toml/hugo.yaml/hugo.json:
[params]prism_syntax_highlighting=true
params:prism_syntax_highlighting:true
{"params":{"prism_syntax_highlighting":true}}
When this option is enabled your site uses
Prism instead of Chroma for code block
highlighting.
Prism is a popular open source syntax highlighter which supports over 200
languages and various
plugins.
Docsy includes JavaScript and CSS files for a basic Prism configuration, which
supports:
Code blocks styled with the Prism Default theme
Copy to clipboard buttons on code blocks
Syntax highlighting for a number of common languages, as specified in the
following Prism download link, Customize your download.
Code blocks with no language
By default, Prism code highlighting styles are not applied to code blocks
without a specified language, instead you get Docsy’s default style of grey with
black text. To apply Prism styling to code blocks with no language or a language
not supported by Prism, specify none as the language after your triple
backticks.
Extending Prism for additional languages or plugins
If the included Prism configuration is not sufficient for your requirements, and
you want to use additional languages or plugins you can replace the included
files with your own.
Replace the included Prism JS and CSS with the files you downloaded:
Copy the Javascript file to static/js/prism.js
Copy the CSS file to static/css/prism.css
Navbar
Styling your project logo and name
The default Docsy navbar (.td-navbar) displays your site identity, consisting
of the following:
Your logo, which is included in the navbar as an inline SVG, styled by .td-navbar .navbar-brand svg.
For the style details, see _nav.scss.
To ensure your logo displays correctly, you may want to resize it and ensure
that it doesn’t have height and width attributes so that its size is fully
responsive. Override the default styling of
.td-navbar .navbar-brand svg or (equivalently)
.td-navbar .navbar-brand__logo as needed.
Your project name, which is the site title. If you don’t want your project
name to appear (for example, because your logo is or contains a
wordmark), then add the following custom styling to your project’s
styles:
.td-navbar.navbar-brand__name{display:none;}
Light/dark mode menu
If you enable this feature, Docsy adds a menu to your navbar that lets users
switch your site’s documentation page display between a default “light” mode,
and a “dark” mode where the text is displayed in a light color on a dark
background.
To enable the display of a light/dark mode menu in the navbar, set params.ui.showLightDarkModeMenu
to true in your project’s configuration file. The dropdown menu appears at the
right, immediately before the search box, if present.
[params][params.ui]showLightDarkModeMenu=true
params:ui:showLightDarkModeMenu:true
{"params":{"ui":{"showLightDarkModeMenu":true}}}
Translucent over cover images
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.
Tables
Docsy applies the following styles to all tables, through the class .td-table:
display: block, which is necessary for tables to be responsive.
This styling configuration gives you responsive tables using Markdown only,
without the need to wrap the table in a <div>. It does, however, mean that all
your tables have display set to block. If you don’t want this, you can
create your own custom styles for tables.
Note
Our table styling goes against the Bootstrap recommendation to wrap
tables with .table-responsive — however, we think letting
users create responsive tables with just Markdown table syntax is more
convenient.
To render a table without Docsy styling, apply the .td-initial class to the
table. From the resulting <table> style base, it is easier to apply your own
custom styles (rather than trying to undo Docsy table styling), as is
illustrated in the following example:
The example above uses Markdown attribute syntax, and might render like this:
Shape
Number of sides
Triangle
3
Square
4
Customizing templates
Add code to head or before body end
If you need to add some code (CSS import, cookie consent, or similar) to the
head section on every page, add the head-end.html partial to your project:
layouts/partials/hooks/head-end.html
And add the code you need in that file. Your partial code is automatically
included just before the end of the theme partial
head.html.
The theme version of
head-end.html
is empty.
Similarly, if you want to add some code right before the body end, create your
own version of the following file:
layouts/partials/hooks/body-end.html
Any code in this file is included automatically at the end of the theme partial
scripts.html.
Both head.html and scripts.html are then used to build Docsy’s
base page layout,
which is used by all the other page templates:
By default, Docsy adds the td-{{ .Kind }} class, where the kind is the kind of
the page, like section, blog, and so on. For example:
<bodyclass="td-section">
Sometimes it’s useful to assign custom classes to a page, or to an entire
section, for example, to apply custom styling. To do so, add the body_class
parameter to the front matter of your page. The value of the parameter will then
be added to the class attribute of your page’s body element.
To add the classes myclass and anotherclass, add the following line to the
front matter of the page:
body_class:myclass anotherclass
The page’s opening body tag will look like this (assuming it is a section page):
<bodyclass="td-section myclass anotherclass">
To apply the custom class to every page of a section or a directory, use the
Front Matter Cascade
feature of Hugo in your configuration file, or in the front matter of the
highest-level page you want to modify.
2.3 - Navigation and Menus
Customize site navigation for your Docsy site.
Docsy provides multiple built-in navigation features for your sites, including site menus, section menus, and page menus. This page shows you how they work and how to configure and customize them to meet your needs.
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 hugo.toml/hugo.yaml/hugo.json.
To add a page or section to this menu, add it to the site’s main menu in either hugo.toml/hugo.yaml/hugo.json or in the destination page’s front matter (in _index.md or _index.html for a section, as that’s the section landing page). For example, here’s how we added the Documentation section landing page to the main menu in this site:
+++title="Welcome to Docsy"linkTitle="Documentation"[menu.main]weight=20pre="<i class='fa-solid fa-book'></i>"+++
---title:"Welcome to Docsy"linkTitle:"Documentation"menu:main:weight:20pre:<i class='fa-solid fa-book'></i>---
{"title":"Welcome to Docsy","linkTitle":"Documentation","menu":{"main":{"weight":20,"pre":"<i class='fa-solid fa-book'></i>"}}}
The menu is ordered from left to right by page weight. So, for example, a section index or page with weight: 30 would appear after the Documentation section in the menu, while one with weight: 10 would appear before it.
If you want to add a link to an external site to this menu, add it in hugo.toml/hugo.yaml/hugo.json, specifying the weight.
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 hugo.toml/hugo.yaml/hugo.json or via page front matter. For example, the following configuration adds the GitHub icon to the GitHub menu item, and a New! alert to indicate that this is a new addition to the menu.
If you configure more than one language in hugo.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.
The section menu, as shown in the left side of the docs section, is automatically built from the content tree. Like the top-level menu, it is ordered by page or section index weight (or by page creation date if weight is not set), with the page or index’s Title, or linkTitle if different, as its link title in the menu. If a section subfolder has pages other than _index.md or _index.html, those pages will appear as a submenu, again ordered by weight. For example, here’s the metadata for this page showing its weight and title:
+++title="Navigation and Search"linkTitle="Navigation and Search"date=2017-01-05T00:00:00.000Zweight=3description='''
Customize site navigation and search for your Docsy site.
'''+++
---title:"Navigation and Search"linkTitle:"Navigation and Search"date:2017-01-05weight:3description:> Customize site navigation and search for your Docsy site.---
{"title":"Navigation and Search","linkTitle":"Navigation and Search","date":"2017-01-05T00:00:00.000Z","weight":3,"description":"Customize site navigation and search for your Docsy site.\n"}
To hide a page or section from the left navigation menu, set toc_hide: true in the front matter.
To hide a page from the section summary on a docs section landing page, set hide_summary: true in the front matter. If you want to hide a page from both the TOC menu and the section summary list, you need to set both toc_hide and hide_summary to true in the front matter.
+++title="My Hidden Page"weight=99toc_hide=truehide_summary=truedescription='''
Page hidden from both the TOC menu and the section summary list.
'''+++
---title:"My Hidden Page"weight:99toc_hide:truehide_summary:truedescription:> Page hidden from both the TOC menu and the section summary list.---
{"title":"My Hidden Page","weight":99,"toc_hide":true,"hide_summary":true,"description":"Page hidden from both the TOC menu and the section summary list.\n"}
Section menu options
By default, the section menu shows the current section fully expanded all the way down. This may make the left nav too long and difficult to scan for bigger sites. Try setting site parameter ui.sidebar_menu_compact = true in hugo.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.
The number of sidebar entries shown per section can be configured using the .ui.sidebar_menu_truncate parameter (default: 100).
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 hugo.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.
The tabbed pane below lists the menu section options you can define in your project configuration file.
You can add icons to the section menu in the sidebar by setting the icon parameter in the page front matter (e.g. icon: fa-solid fa-screwdriver-wrench).
You can find a complete list of icons to use in the FontAwesome documentation. Docsy includes the free FontAwesome icons by default.
Out of the box, if you want to use icons, you should define icons for all items on the same menu level in order to ensure an appropriate look. If the icons are used in a different way, individual CSS adjustments are likely necessary.
Add manual links to the section menu
By default the section menu is entirely generated from your section’s pages. If you want to add a manual link to this menu, such as a link to an external site or a page in a different section of your site, you can do this by creating a placeholder page file in the doc hierarchy with the appropriate weight and some special parameters in its metadata (frontmatter) to specify the link details.
To create a placeholder page, create a page file as usual in the directory where you want the link to show up in the menu, and add a manualLink parameter to its metadata. If a page has manualLink in its metadata, Docsy generates a link for it in the section menu for this page and in the section index (the list of the child pages of a section on a landing page - see description in the Docsy docs), but the link destination is replaced by the value of manualLink. The link text is the title (or linkTitle if set) of your placeholder page. You can optionally also set the title attribute of the link with the parameter manualLinkTitle and a link target with manualLinkTarget - for example if you want an external link to open in a new tab you can set the link target to _blank. Docsy automatically adds rel=noopener to links that open new tabs as a security best practice.
You can also use manualLink to add an additional cross reference to another existing page of your site. For internal links you can choose to use the parameter manualLinkRelref instead of manualLink to use the built-in Hugo function relref. If relref can’t find a unique page in your site, Hugo throws a error message.
Note
Although all generated menu and landing page links based on your placeholder file are set according to the parameters manualLink or manualLinkRelref, Hugo still generates a regular HTML site page for the file, albeit one with no generated links to it. To avoid confusion if users accidentally land on a generated placeholder page, we recommend specifying the URL for the external link in the normal content and / or page description of the page.
Breadcrumb navigation
Breadcrumb navigation links appear at the top of each page by default. To disable breadcrumb navigation, set site param ui.breadcrumb_disable = true in hugo.toml.
Breadcrumb navigation links are also shown for each item on the taxonomy results page (i.e. when you click one of the taxonomy labels, e.g. Tags/Categories). These breadcrumbs can be disabled in hugo.toml by setting site param ui.taxonomy_breadcrumb_disable = true.
The tabbed pane below lists the breadcrumb navigation options you can define in your project configuration file.
The heading self-link anchor class is .td-heading-self-link, which you can
customize for your project. By default, the heading self-link style has these defaults:
The self-link symbol is #.
The symbol is always visible on mobile and touch devices, otherwise it is only
visible on hover or focus.
Your projects can also reuse (in your own custom heading render hook) or
override the heading self-link template
_default/_markup/_td-heading-self-link.html, which is defined in
layouts/_default/_markup/td-render-heading.html.
2.4 - Search
Let users search your Docsy site with a choice of configurable 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. Search results are displayed as a pop-up. 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 project configuration file, 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.
You can only enable a single search option at a time
If you accidentally enable more than one search option in your project
configuration file, you will get a warning at build time, and undetermined
behavior when serving your site.
Disabling the sidebar search box
By default, the search box appears in both the top navigation bar and at the top of the sidebar left navigation pane. If you don’t want the sidebar search box, set the site parameter sidebar_search_disable to true in hugo.toml/hugo.yaml/hugo.json:
[params.ui]sidebar_search_disable=true
params:ui:sidebar_search_disable:true
{"params":{"ui":{"sidebar_search_disable":true}}}
Configure search with a Google Custom Search Engine
By default Docsy uses a Google Custom Search Engine (GCSE) to search your site. To enable this feature, you’ll first need to make sure that you have built and deployed a production version of your site, as otherwise your site won’t be crawled and indexed.
Setting up site search
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.
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.
Once you have your search engine set up, you can add the feature to your site:
Ensure you have a Markdown file in content/en/search.md (and one per other languages if needed) to display your search results. It only needs a title and layout: search, as in the following example:
+++title="Search Results"layout="search"+++
---title:Search Resultslayout:search---
{"title":"Search Results","layout":"search"}
Add your Google Custom Search Engine ID to the site params in hugo.toml/hugo.yaml/hugo.json. You can add different values per language if needed.
[params]# 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 hugo.toml from the example site and want to disable search, just comment out or remove the relevant line.
Algolia DocSearch
As an alternative to GCSE, you can use Algolia
DocSearch, which is
free for public documentation sites. Docsy supports Algolia DocSearch v3.
Algolia v2 is deprecated
Docsy previously supported Algolia DocSearch v2, which is now deprecated. If you
are an existing Algolia DocSearch v2 user and want to use the latest Docsy
version, follow the migration
instructions in the
DocSearch documentation to update your DocSearch code snippet.
Sign up for Algolia DocSearch
Complete the form at https://docsearch.algolia.com/apply.
Proceed to the next step once you’ve received Algolia DocSearch
parameters for your project.
Eager to test DocSearch?
Docsy defaults to the Algolia test-site parameters when
none are provided. To enable search over the Algolia test, define
params.search.algolia without any other fields, as outlined next.
To learn more about Algolia DocSearch V3, see Getting
started.
When you’ve completed these steps, Algolia search should be enabled on your
site. Search results are displayed as a pop-up, so you don’t need to add any
search results page.
Customizing Algolia templates
You can customize or disable Docsy’s default Algolia support by creating the
following template files:
layouts/partials/algolia/head.html used by head.html to load Algolia
DocSearch styles. It also issues a deprecation warning for
params.algolia_docsearch.
layouts/partials/algolia/scripts.html used by scripts.html to load and
configure Algolia DocSearch.
Leave either file empty to disable Docsy’s implementation.
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:
Enable local search in hugo.toml/hugo.yaml/hugo.json.
[params]offlineSearch=true
params:offlineSearch:true
{"params":{"offlineSearch":true}}
Remove or comment out any GCSE ID in hugo.toml/hugo.yaml/hugo.json and ensure Algolia DocSearch is set to false, as you can only have one type of search enabled. See Disabling GCSE search.
Once you’ve completed these steps, local search is enabled for your site and results appear in a drop down when you use the search box.
Tip
If you’re testing this locally using Hugo’s local server functionality, you need to build your offline-search-index.xxx.json file first by running hugo. If you have the Hugo server running while you build offline-search-index.xxx.json, you may need to stop the server and restart it in order to see your search results.
Changing the summary length of the local search results
You can customize the summary length by setting offlineSearchSummaryLength in hugo.toml/hugo.yaml/hugo.json.
#Enable offline search with Lunr.js[params]offlineSearch=trueofflineSearchSummaryLength=200
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 hugo.toml/hugo.yaml/hugo.json, the Docsy theme adds a
version selector drop down to the top-level menu. You specify a URL and a name
for each version you would like to add to the menu, as in the following example:
# Add your release versions here[[params.versions]]version="master"url="https://master.kubeflow.org"[[params.versions]]version="v0.2"url="https://v0-2.kubeflow.org"[[params.versions]]version="v0.3"url="https://v0-3.kubeflow.org"
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 site parameter version_menu in hugo.toml/hugo.yaml/hugo.json:
[params]version_menu="Releases"
params:version_menu:Releases
{"params":{"version_menu":"Releases"}}
If you set the version_menu_pagelinks parameter to true, then links in the version drop-down menu
point to the current page in the other version, instead of the main page.
This can be useful if the document doesn’t change much between the different versions.
Note that if the current page doesn’t exist in the other version, the link will be broken.
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:
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
hugo.toml/hugo.yaml/hugo.json file:
Set the site parameter archived_version to true:
[params]archived_version=true
params:archived_version:true
{"params":{"archived_version":true}}
Set the site parameter version to the version of the archived doc set. For
example, if the archived docs are for version 0.1:
[params]version="0.1"
params:version:0.1
{"params":{"version":"0.1"}}
Make sure that site parameter 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:
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 delimiters
As illustrated below, using the bracket styled shortcode delimiter,
{{<...>}}, tells Hugo that the inner content is HTML/plain text and needs
no further processing. By using the delimiter {{%...%}}, Hugo will treat
the shortcode body as Markdown. You can use both styles in your pages.
Shortcode blocks
The theme comes with a set of custom Page Block shortcodes that can be used to compose landing pages, about pages, and similar.
These blocks share some common parameters:
height
A pre-defined height of the block container. One of min, med, max, full, or auto. Setting it to full will fill the Viewport Height, which can be useful for landing pages.
color
The block will be assigned a color from the theme palette if not provided, but you can set your own if needed. You can use all of Bootstrap’s color names, theme color names or a grayscale shade. Some examples would be primary, white, dark, warning, light, success, 300, blue, orange. This will become the background color of the block, but text colors will adapt to get proper contrast.
blocks/cover
The blocks/cover shortcode creates a landing page type of block that fills the top of the page.
{{<blocks/covertitle="Welcome!"image_anchor="center"height="full"color="primary">}}
<divclass="mx-auto"><aclass="btn btn-lg btn-primary me-3 mb-4"href="{{< relref "/docs">}}">
Learn More <iclass="fa-solid fa-circle-right ms-2"></i></a><aclass="btn btn-lg btn-secondary me-3 mb-4"href="https://example.org"> Download <iclass="fa-brands fa-github ms-2"></i></a><pclass="lead mt-5">This program is now available in <ahref="#">AppStore!</a></p><divclass="mx-auto mt-5"> {{<blocks/link-downcolor="info">}}
</div></div>{{< /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.
image_anchor
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.
Tip
If you also include the word featured in the image name, e.g. my-featured-background.jpg, it will also be used as the Twitter Card image when shared.
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/sectioncolor="dark"type="row">}}{{%blocks/featureicon="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/featureicon="fa-brands fa-github"title="Contributions welcome!"url="https://github.com/gohugoio/hugo"%}}We do a [Pull Request](https://github.com/gohugoio/hugo/pulls) contributions workflow on **GitHub**. New users are always welcome!
{{%/blocks/feature%}}{{%blocks/featureicon="fa-brands fa-x-twitter"title="Follow us on Twitter!"url="https://twitter.com/GoHugoIO"%}}For announcement of latest features etc.
{{%/blocks/feature%}}{{</blocks/section>}}
Parameter
Default
Description
height
See above.
color
See above.
type
Specify “container” (the default) if you want a general container, or “row” if the section will contain columns – which must be immediate children.
blocks/feature
{{%blocks/featureicon="fa-brands fa-github"title="Contributions welcome!"url="https://github.com/gohugoio/hugo"%}}We do a [Pull Request](https://github.com/gohugoio/hugo/pulls) contributions workflow on **GitHub**. New users are always welcome!
{{%/blocks/feature%}}
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.
The alert shortcode creates an alert block that can be used to display notices or warnings.
{{%alerttitle="Warning"color="warning"%}}This is a warning.
{{%/alert%}}
Renders to:
Warning
This is a warning.
Parameter
Default
Description
color
primary
One of the theme colors, eg primary, info, warning etc.
pageinfo
The pageinfo shortcode creates a text box that you can use to add banner information for a page: for example, letting users know that the page contains placeholder content, that the content is deprecated, or that it documents a beta feature.
{{%pageinfocolor="info"%}}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.
imgproc
The imgproc shortcode finds an image in the current Page Bundle and scales it given a set of processing instructions.
{{%imgprocspruceFill"400x450"%}}Norway Spruce *Picea abies* shoot with foliage buds.
{{%/imgproc%}}
Use the syntax above if the inner content and/or the byline parameter of your shortcode is authored in markdown. In case of HTML content, use <> as innermost delimiters: {{< imgproc >}}<b>HTML</b> content{{< /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:
+++[[resources]]src="**spruce*.jpg"[resources.params]byline="*Photo*: Bjørn Erik Pedersen / CC-BY-SA"+++
---resources:- src:"**spruce*.jpg"params:byline:"*Photo*: Bjørn Erik Pedersen / CC-BY-SA"---
{"resources":[{"src":"**spruce*.jpg","params":{"byline":"*Photo*: Bjørn Erik Pedersen / CC-BY-SA"}}]}
Parameter
Description
1
The image filename or enough of it to identify it (we do Glob matching)
You can place the swaggerui shortcode anywhere inside a page with the swagger layout; it renders Swagger UI using any OpenAPI YAML or JSON file as source. This file can be hosted anywhere you like, for example in your site’s root /static folder.
+++title="Pet Store API"type="swagger"weight=1description="Reference for the Pet Store API"+++{{<swaggeruisrc="/openapi/petstore.yaml">}}
---title:"Pet Store API"type:swaggerweight:1description:Reference for the Pet Store API---{{< swaggerui src="/openapi/petstore.yaml" >}}
{"title":"Pet Store API","type":"swagger","weight":1,"description":"Reference for the Pet Store API"}{{<swaggeruisrc="/openapi/petstore.yaml">}}
You can customize Swagger UI’s look and feel by overriding Swagger’s CSS in themes/docsy/assets/scss/_swagger.scss.
Warning
This shortcode relies on JavaScript libraries hosted on unpkg. Make sure that you can access unpkg from your network when building or loading your site.
redoc
The redoc shortcode uses the open-source Redoc tool to render reference API documentation from an OpenAPI YAML or JSON file. This can be hosted anywhere you like, for example in your site’s root /static folder, but you can use a URL as well, for example:
---title:"Pet Store API"type:docsweight:1description:Reference for the Pet Store API---{{< redoc "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v2.0/yaml/petstore.yaml" >}}
If true the shortcode tries to calculate the needed height for the embedded content using JavaScript, as described here: https://stackoverflow.com/a/14618068. 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.
There are several tools you can use to check if a website can be embedded via iframe - e.g.: https://gf.dev/x-frame-options-test. Be aware that when this test says “Couldn’t find the X-Frame-Options header
in the response headers.” you CAN embed it, but when the test says “Great! X-Frame-Options header was found in the HTTP response headers as highlighted below.”, you CANNOT - unless it has been explicitly enabled for your site.
Tabbed panes
Sometimes it’s very useful to have tabbed panes when authoring content. One common use-case is to show multiple syntax highlighted code blocks that showcase the same problem, and how to solve it in different programming languages. As an example, the tabbed pane below shows the language-specific variants of the famous Hello world! program one usually writes first when learning a new programming language:
The Docsy template provides two shortcodes tabpane and tab that let you easily create tabbed panes. To see how to use them, have a look at the following code block, which renders to a right aligned pane with one disabled and three active tabs:
This code translates to the right aligned tabbed pane below, showing a Welcome! greeting in English, German or Swahili:
Welcome!
Herzlich willkommen!
Karibu sana!
Shortcode details
Tabbed panes are implemented using two shortcodes: tabpane containing two or
more nested tabs.
tabpane
The tabpane shortcode, which is the container element for the tabs, supports
the following named parameters, all of which are optional:
lang: the default code-block language to use for all contained tabs
highlight: parameter passed on to the code-block highlight function,
as described below
langEqualsHeader: set to true when header text matches the tab language.
persist: one of header, lang, or disabled
persistLang: deprecated, use persist instead
right: set to true if you want right-aligned tabs
text: set to true if the content of all contained tabs are text. Default
is false and assumes the content is code.
The value of the optional parameters lang and highlight are passed on as
second LANG and third OPTIONS arguments to Hugo’s built-in highlight
function, which is used to render the code blocks of the individual tabs.
Tab selection is persisted by default. When unspecified, persist defaults to
header when text=true or lang is set; otherwise persist defaults to
lang. To disable tab persistence, set persist=disable.
tab
The tab shortcode represent the tabs you want to show. It supports the
following named parameters, all of which are optional:
header: defines the tab’s header text. When omitted it defaults to text of
the form “Tab n”. You can omit the parameter name if it is the only tab
parameter:
{{< tab "My tab header" >}} … {{< /tab >}}
lang: code-block language for code tabs
highlight: parameter passed on to the code-block highlight function
right: set to true in order to split tab panes into a left aligned and a
right aligned tab groups. Specify right=true in the dividing tab. By using
right=true more than once, you can even render multiple tab groups.
disabled: set to true to disable a tab.
text: set to true for text tabs. By default tabs are assumed to
contain code.
For enabled tabs, there are two modes for content display, code representation
and textual representation:
By default, the tab’s content is rendered as a code block. In order to get
proper syntax highlighting, specify the named parameter lang –and
optionally the parameter highlight– for each tab. Parameters set in the
parent tabpane shortcode will be overwritten.
If the contents of your tabs should be rendered as text with different styles
and optional images, specify text=true as parameter of your tab:
Reminder: If your content is markdown, use the percent sign % as
delimiter for your tab shortcode, like this:
{{% tab %}} Your \*\*markdown\*\* content {{% /tab %}}
Card panes
When authoring content, it’s sometimes very useful to put similar text blocks or code fragments on card like elements, which can be optionally presented side by side. Let’s showcase this feature with the following sample card group which shows the first four Presidents of the United States:
George Washington
*1732 †1799
President: 1789 – 1797
John Adams
* 1735 † 1826
President: 1797 – 1801
Thomas Jefferson
* 1743 † 1826
President: 1801 – 1809
James Madison
* 1751 † 1836
President: 1809 – 1817
Docsy supports creating such card panes via different shortcodes:
The cardpane shortcode which is the container element for the various cards to be presented.
The card shortcodes, with each shortcode representing an individual card. While cards are often presented inside a card group, a single card may stand on its own, too. A card shortcode can hold programming code, text, images or any other arbitrary kind of markdown or HTML markup as content. In case of programming code, cards provide automatic code-highlighting and other optional features like line numbers, highlighting of certain lines, ….
Shortcode card: textual content
Make use of the card shortcode to display a card. The following code sample demonstrates how to code a card element:
{{<cardheader="**Imagine**"title="Artist and songwriter: John Lennon"subtitle="Co-writer: Yoko Ono"footer="">}}Imagine there's no heaven, It's easy if you try<br/>No hell below us, above us only sky<br/>Imagine all the people living for today…
…
{{</card>}}
This code translates to the left card shown below, showing the lyrics of John Lennon’s famous song Imagine. A second explanatory card element to the right indicates and explains the individual components of a card:
Imagine
Artist and songwriter: John Lennon
Co-writer: Yoko Ono
Imagine there’s no heaven, It’s easy if you try No hell below us, above us only sky Imagine all the people living for today…
Imagine there’s no countries, it isn’t hard to do Nothing to kill or die for, and no religion too Imagine all the people living life in peace…
Imagine no possessions, I wonder if you can No need for greed or hunger - a brotherhood of man Imagine all the people sharing all the world…
You may say I’m a dreamer, but I’m not the only one I hope someday you’ll join us and the world will live as one
Header: specified via named parameter Header
Card title: specified via named parameter title
Card subtitle: specified via named parameter subtitle
Content: inner content of the shortcode, this may be plain text or formatted text, images, videos, … . If your content is markdown, use the percent sign % as outermost delimiter of your card shortcode, your markup should look like {{% card %}}Your **markdown** content{{% /card %}}. In case of HTML content, use square brackets <> as outermost delimiters: {{< card >}}Your <b>HTML</b> content{{< /card >}}
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: programming code
If you want to display programming code on your card, set the named parameter code of the card to true. The following sample demonstrates how to code a card element with the famous Hello world! application coded in C:
If called with parameter code=true, the card shortcode can optionally hold the named parameters lang and/or highlight. The values of these optional parameters are passed on as second LANG and third OPTIONS arguments to Hugo’s built-in highlight function which is used to render the code block presented on the card.
Card groups
Displaying two ore more cards side by side can be easily achieved by putting them between the opening and closing elements of a cardpane shortcode.
The general markup of a card group resembles closely the markup of a tabbed pane:
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")
.listFiles(File::isHidden);
Include external files
Sometimes there’s content that is relevant for several documents, or that is
maintained in a file that is not necessarily a document. For situations like
these, the readfile shortcode allows you to import the contents of an external
file into a document.
Reuse documentation
In case you want to reuse some content in several documents, you can write said
content in a separate file and include it wherever you need it.
For example, suppose you have a file called installation.md with the following
contents:
## Installation
{{%alerttitle="Note"color="primary"%}}Check system compatibility before proceeding.
{{%/alert%}}1. Download the installation files.
1. Run the installation script
`sudo sh install.sh`
1. Test that your installation was successfully completed.
You can import this section into another document:
The following section explains how to install the database:
{{%readfile"installation.md"%}}
This is rendered as if the instructions were in the parent document. Hugo
v0.101.0+ is required for imported files containing shortcodes to be rendered
correctly.
The following section explains how to install the database:
Installation
Note
Check system compatibility before proceeding.
Download the installation files.
Run the installation script
sudo sh install.sh
Test that your installation was successfully completed.
The parameter is the relative path to the file. Only relative paths
under the parent file’s working directory are supported.
For files outside the current working directory you can use an absolute path
starting with /. The root directory is the /content folder.
Include code files
Suppose you have an includes folder containing several code samples you want
to use as part of your documentation. You can use readfile with some
additional parameters:
To create a new pipeline, follow the next steps:
1. Create a configuration file `config.yaml`:
{{<readfilefile="includes/config.yaml"code="true"lang="yaml">}}1. Apply the file to your cluster `kubectl apply config.yaml`
This code automatically reads the content of includes/config.yaml and inserts it
into the document. The rendered text looks like this:
The conditional-text shortcode allows you to show or hide parts of your content depending on the value of the buildCondition parameter set in your configuration file. This can be useful if you are generating different builds from the same source, for example, using a different product name. This shortcode helps you handle the minor differences between these builds.
{{% conditional-text include-if="foo" %}}
This text appears in the output only if `buildCondition = "foo" is set in your config file`.
{{% /conditional-text %}}
{{% conditional-text exclude-if="bar" %}}
This text does not appear in the output if `buildCondition = "bar" is set in your config file`.
{{% /conditional-text %}}
If you are using this shortcode, note that when evaluating the conditions, substring matches are matches as well. That means, if you set include-if="foobar", and buildcondition = "foo", you have a match!
2.7 - Logos and Images
Add and customize logos, icons, and images in your project.
Add your logo
By default, Docsy shows a site logo at the start of the navbar, that is, at the
extreme left. Place your project’s SVG logo in assets/icons/logo.svg. This
overrides the default Docsy logo in the theme.
If you don’t want a logo to appear in the navbar, then set site parameter navbar_logo
to false in your project’s config:
Docsy includes the free FontAwesome icons by default, including logos for sites like GitHub and Stack Overflow. You can view all available icons in the FontAwesome documentation, including the FontAwesome version when the icon was added and whether it is available for free tier users. Check Docsy’s package.json and release notes for Docsy’s currently included version of FontAwesome.
The easiest way to do this is to create a set of favicons via http://cthedot.de/icongen (which lets you create a huge range of icon sizes and options from a single image) and/or https://favicon.io, and put them in your site project’s static/favicons directory. This will override the default favicons from the theme.
Note that https://favicon.io doesn’t create as wide a range of sizes as Icongen but does let you quickly create favicons from text: if you want to create text favicons you can use this site to generate them, then use Icongen to create more sizes (if necessary) from your generated .png file.
If you have special favicon requirements, you can create your own layouts/partials/favicons.html with your links.
Add images
Landing pages
Docsy’s blocks/cover shortcode make it easy to add large cover images to your landing pages. The shortcode looks for an image with the word “background” in the name inside the landing page’s Page Bundle - so, for example, if you’ve copied the example site, the landing page image in content/en/_index.html is content/en/featured-background.jpg.
You specify the preferred display height of a cover block container (and hence its image) using the block’s height parameter. For a full viewport height, use full:
{{<blocks/covertitle="Welcome to the Docsy Example Project!"image_anchor="top"height="full">}}
...
{{< /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/covertitle="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.8 - 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 hugo.toml/hugo.yaml/hugo.json file for the “section” type:
[outputs]section=["HTML","RSS","print"]
outputs:section:- HTML- RSS- print
{"outputs":{"section":["HTML","RSS","print"]}}
The site should then show a “Print entire section” link in the right hand navigation.
Further Customization
Disabling the ToC
To disable showing the the table of contents in the printable view, set the disable_toc param to true, either in the page front matter, or in hugo.toml/hugo.yaml/hugo.json:
+++…disable_toc=true…+++
---…disable_toc:true…---
{…,"disable_toc":true,…}
[params.print]disable_toc=true
params:print:disable_toc:true
{"params":{"print":{"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.9 - Analytics, User Feedback, and SEO
Add Google Analytics tracking to your site, collect user feedback and learn about the page description meta tag.
You will need an analytics ID for your website before proceeding
(technically it’s called a measurement ID or property ID but we’ll use the term
“analytics ID” in this guide). If you don’t have one, see the How to get
started section of Introducing Google Analytics 4 (GA4).
Tip
Your project’s analytics ID is a string that starts with G- (a GA4
measurement ID) or UA- (a universal analytics property ID).
Setup
Enable Google Analytics by adding your project’s analytics ID to the site
configuration file. For details, see Configure Google Analytics.
Deprecation note and warning
While you can configure your project’s analytics ID by setting either the
top-level googleAnalytics config parameter or services.googleAnalytics.id,
googleAnalytics was deprecated in Hugo 0.120.0 and
will be removed in a future release.
Analytics are enabled only for production builds (called “environments”
in Hugo terminology). For information about Hugo environments and how to set
them, see the following discussion.
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.
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 your project’s configuration file.
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!
Setup
Version note
As of Docsy version 0.8.0, feedback will be enabled whether
site.Config.Services.GoogleAnalytics.ID is set or not. This supports the use
case where analytics is configured outside of Docsy.
Open your project’s Hugo configuration file.
Set the response text that users see after clicking Yes or No.
[params.ui.feedback]enable=trueyes='Glad to hear it! Please <a href="https://github.com/USERNAME/REPOSITORY/issues/new">tell us how we can improve</a>.'no='Sorry to hear that. Please <a href="https://github.com/USERNAME/REPOSITORY/issues/new">tell us how we can improve</a>.'
params:ui:feedback:enable:true'yes':>- Glad to hear it! Please <a href="https://github.com/USERNAME/REPOSITORY/issues/new">
tell us how we can improve</a>.'no':>- Sorry to hear that. Please <a href="https://github.com/USERNAME/REPOSITORY/issues/new">
tell us how we can improve</a>.
{"params":{"ui":{"feedback":{"enable":true,"yes":"Glad to hear it! Please <a href=\"https://github.com/USERNAME/REPOSITORY/issues/new\"> tell us how we can improve</a>.","no":"Sorry to hear that. Please <a href=\"https://github.com/USERNAME/REPOSITORY/issues/new\"> tell us how we can improve</a>."}}}}
Save the edits to your configuration file.
By default, Docsy emits an event value of 100 when a user clicks “yes”. You can
change this value by setting params.ui.feedback.max_value to a positive
integer. Docsy uses 0 for “no” events.
Access the feedback data
Page feedback is reported to Google Analytics through events.
Version note
As of Docsy version 0.8.0, page feedback is reported as custom page_helpful events,
rather than click events.
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.
Open Google Analytics.
Open Reports > Engagement > Events.
Click page_helpful in the events table. If there is no page_helpful
event, then none have been registered for the selected period. Adjust the
period as necessary.
Note that you might be required to create a custom report if you’d like better
visualize individual data points (per page) along with average values.
Disable feedback on a single page
Add the parameter hide_feedback to the page’s front matter and set it to
true.
+++hide_feedback=true+++
---hide_feedback:true---
{"hide_feedback":true}
Disable feedback on all pages
Set params.ui.feedback.enable to false in
hugo.toml/hugo.yaml/hugo.json:
[params.ui.feedback]enable=false
params:ui:feedback:enable:false
{"params":{"ui":{"feedback":{"enable":false}}}}
Add a contact form with Fabform
You can create a contact form for your site and collect your form submissions at
fabform.io. To use this feature, you first need to sign up
for an account with Fabform. The following example shows how to add a simple
form that collects the user’s email address to your site source:
Google
recommends
using the description meta tag to tell search engines what your page is about.
For each generated page, Docsy will set the content of the meta description by
using the first of the following that is defined:
Add more meta tags as needed to your project’s copy of the head-end.html
partial. For details, see Customizing templates.
2.10 - Repository Links and other page information
Help your users interact with page source and view page-source information.
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/new-page-template.md 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”. Since GitLab can handle the same link scheme, it should work as well. 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.
Link configuration
There are four site variables you can configure in hugo.toml/hugo.yaml/hugo.json to set up links, as well as one in your page metadata.
github_repo
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.
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.
[params]github_subdir="userguide"
params:github_subdir:userguide
{"params":{"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.
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.
[params]github_branch="release"
params:github_branch:release
{"params":{"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"[cascade]github_repo="https://github.com/some-username/another-repo/"github_subdir="docs"path_base_for_github_subdir="content/some-section"…+++
---title:Some super sectioncascade:github_repo:https://github.com/some-username/another-repo/github_subdir:docspath_base_for_github_subdir:content/some-section…---
{"title":"Some super section","cascade":{"github_repo":"https://github.com/some-username/another-repo/","github_subdir":"docs","path_base_for_github_subdir":"content/some-section"}}
As an example, consider a page at the path
content/some-section/subpath/some-page.md with github_branch globally set to
main. The index page settings above will generate the following edit link for
some-page.md:
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:
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 README.md in the originating repo:
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.
Disabling links
You can use CSS to selectively hide links. For example, add the following to
your projects’s _styles_project.scss file to hide
Create child page links from all pages (optionally with a !important
modifier – not shown):
.td-page-meta__child{display:none;}
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.
Version note
Class names using the --KIND suffix were deprecated as of v0.9.0.
Last-modified page metadata
To have page-source metadata displayed at the bottom of documentation pages and
blog posts, set the GitInfo configuration parameter to true, and ensure that
params.github_repo is defined.
A last-modified page note looks something like this:
Once enabled site-wide, you can selectively hide last-modified notes in a page
or section by declaring the following style (optionally with a !important
modifier — not shown):
.td-page-meta__lastmod{display:none;}
2.11 - Taxonomy Support
Structure the content using taxonomies like tags, categories, labels.
Docsy supports Hugo’s Taxonomies (see: https://gohugo.io/content-management/taxonomies/) in its docs and blog section. You can see the default layout and can test the behavior of the generated links on this page.
Terminology
To understand the usage of taxonomies you should understand the following terminology:
Taxonomy
a categorization that can be used to classify content - e.g.: Tags, Categories, Projects, People
Term
a key within the taxonomy - e.g. within projects: Project A, Project B
Value
a piece of content assigned to a term - e.g. a page of your site, that belongs to a specific project
If you want to enable taxonomies in Docsy you have to delete (or comment out) this line in your project’s hugo.toml/hugo.yaml/hugo.json. 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 configuration file. 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:
You can use the following parameters in your project’s hugo.toml/hugo.yaml/hugo.json 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:
[params.taxonomy]taxonomyCloud=["projects","tags"]# set taxonomyCloud = [] to hide taxonomy cloudstaxonomyCloudTitle=["Our Projects","Tag Cloud"]# if used, must have same length as taxonomyCloudtaxonomyPageHeader=["tags","categories"]# set taxonomyPageHeader = [] to hide taxonomies on the page headers
params:taxonomy:taxonomyCloud:- projects # remove all entries- tags # to hide taxonomy cloudstaxonomyCloudTitle:# if used, must have the same- Our Projects # number of entries as taxonomyCloud- Tag CloudtaxonomyPageHeader:- tags # remove all entries- categories # to hide taxonomy clouds
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 don’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 don’t set the parameters taxonomyCloud resp. taxonomyPageHeader the taxonomy clouds resp. assigned terms for all defined taxonomies will be generated.
Partials
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.
taxonomy_terms_article
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:
The partial taxonomy_terms_article_wrapper is a wrapper for the partial taxonomy_terms_article with the only parameter context (most of the time the current page or context .) and checks the taxonomy parameters of your project’s hugo.toml/hugo.yaml/hugo.json to loop threw all listed taxonomies in the parameter taxonomyPageHeader resp. all defined taxonomies of your page, if taxonomyPageHeader isn’t set.
taxonomy_terms_cloud
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:
As an example this will gave you for following HTML markup for the taxonomy categories:
<divclass="taxonomy taxonomy-terms-cloud taxo-categories"><h5class="taxonomy-title">Cloud of Categories</h5><ulclass="taxonomy-terms"><li><aclass="taxonomy-term"href="//localhost:1313/categories/category-1/"data-taxonomy-term="category-1"><spanclass="taxonomy-label">category 1</span><spanclass="taxonomy-count">3</span></a></li><li><aclass="taxonomy-term"href="//localhost:1313/categories/category-2/"data-taxonomy-term="category-2"><spanclass="taxonomy-label">category 2</span><spanclass="taxonomy-count">1</span></a></li><li><aclass="taxonomy-term"href="//localhost:1313/categories/category-3/"data-taxonomy-term="category-3"><spanclass="taxonomy-label">category 3</span><spanclass="taxonomy-count">2</span></a></li><li><aclass="taxonomy-term"href="//localhost:1313/categories/category-4/"data-taxonomy-term="category-4"><spanclass="taxonomy-label">category 4</span><spanclass="taxonomy-count">6</span></a></li></ul></div>
taxonomy_terms_clouds
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 your project’s hugo.toml/hugo.yaml/hugo.json 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.12 - 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, Diagrams.net, 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 \\(ax^2 + bx + c= 0\\) and they are \\(x = {-b \pm\sqrt{b^2-4ac}\over 2a}\\).
When \(a \ne 0\), there are two solutions to \(ax^2 + 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 its own line:
The probability of getting \\(k\\) heads when flipping \\(n\\) coins is:
```math
\tag*{(1)} P(E) = {n \choose k} p^k (1-p)^{n-k}
```
The formula itself is written inside a GLFM math block. The above code fragment renders to:
The probability of getting \(k\) heads when flipping \(n\) coins is:
This wiki page provides in-depth information about typesetting mathematical formulae using the \(\LaTeX\) typesetting system.
Activating and configuring \(\KaTeX\) support
Auto activation
As soon as you use a math code block on your page, support of \(\KaTeX\) is automatically enabled.
Manual activation (no math code block present or hugo 0.92 or lower)
If you want to use inline formulae and don’t have a math code block present in your page which triggers auto activation, you need to manually activate \(\KaTeX\) support. The easiest way to do so is to add a math attribute to the frontmatter of your page and set it to true:
+++math=true+++
---math:true---
{"math":true}
If you use formulae in most of your pages, you can also enable sitewide \(\KaTeX\) support inside the Docsy theme. To do so update hugo.toml/hugo.yaml/hugo.json:
[params.katex]enable=true
params:katex:enable:true
{"params":{"katex":{"enable":true}}}
Additionally, you can customize various \(\KaTeX\) options inside hugo.toml/hugo.yaml/hugo.json, if needed:
[params.katex]# enable/disable KaTeX supportenable=true# Element(s) scanned by auto render extension. Default: document.bodyhtml_dom_element="document.body"[params.katex.options]# 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=falseerrorColor="#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.[[params.katex.options.delimiters]]left="$$"right="$$"display=true[[params.katex.options.delimiters]]left="$"right="$"display=false[[params.katex.options.delimiters]]left="\\("right="\\)"display=false[[params.katex.options.delimiters]]left="\\["right="\\]"display=true
params:katex:enable:true# enable/disable KaTeX supporthtml_dom_element: document.body # Element(s) scanned by auto render extension. Default:document.bodyoptions:# 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:falseerrorColor:'#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.delimiters:- 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 mhchemextension that makes the mhchem package accessible when authoring content for the web. With mhchem extension enabled, you can easily include chemical equations into your page. An equation 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 need to be displayed on their own line. Use a code block adorned with chem in order to achieve this:
The manual for mchem’s input syntax provides in-depth information about typesetting chemical formulae and physical units using the mhchem tool.
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.
Activating rendering support for chemical formulae
Auto activation
As soon as you use a chem code block on your page, rendering support for chemical equations is automatically enabled.
Manual activation (no chem code block present or hugo 0.92 or lower)
If you want to use chemical formulae inline and don’t have a chem code block present in your page which triggers auto activation, you need to manually activate rendering support for chemical formulae. The easiest way to do so is to add a chem attribute to the frontmatter of your page and set it to true:
+++chem=true+++
---chem:true---
{"chem":true}
If you use formulae in most of your pages, you can also enable sitewide rendering support for chemical formulae inside the Docsy theme. To do so, enable mhchem inside your hugo.toml/hugo.yaml/hugo.json:
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 sequence diagram:
```mermaid
sequenceDiagram
autonumber
Docsy user->>Discussion board: Ask question
Discussion board->>Community member: read question
loop Different strategies
Community member->>Test instance: Investigate issue raised
end
Note right of Community member: After hours of investigation:
Test instance-->>Community member: Come up with solution
Community member-->>Discussion board: Propose solution
Discussion board-->>Docsy user: check proposed solution
Docsy user->>Discussion board: Mark question as resolved
Docsy user->>Docsy user: Being happy
```
which is automatically rendered to:
sequenceDiagram
autonumber
Docsy user->>Discussion board: Ask question
Discussion board->>Community member: read question
loop Different strategies
Community member->>Test instance: Investigate issue raised
end
Note right of Community member: After hours of investigation:
Test instance-->>Community member: Come up with solution
Community member-->>Discussion board: Propose solution
Discussion board-->>Docsy user: check proposed solution
Docsy user->>Discussion board: Mark question as resolved
Docsy user->>Docsy user: Being happy
Support of Mermaid diagrams is automatically enabled as soon as you use a mermaid code block on your page.
By default, docsy pulls in the latest officially released version of Mermaid at build time. If that doesn’t fit your needs, you can specify the wanted mermaid version inside your configuration file hugo.toml/hugo.yaml/hugo.json:
[params.mermaid]version="10.9.0"
params:mermaid:version:10.9.0
{"params":{"mermaid":{"version":"10.9.0"}}}
If needed, you can define custom settings for your diagrams, such as themes, padding in your hugo.toml/hugo.yaml/hugo.json.
Settings can also be overridden on a per-diagram basis by making use of a frontmatter config block at the start of the diagram definition.
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.
```plantuml
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 hugo.toml/hugo.yaml/hugo.json:
[params.plantuml]enable=true
params:plantuml:enable:true
{"params":{"plantuml":{"enable":true}}}
Other optional settings are:
[params.plantuml]enable=truetheme="default"# Set url to plantuml server# default is http://www.plantuml.com/plantuml/svg/svg_image_url="https://www.plantuml.com/plantuml/svg/"# By default the plantuml implementation uses <img /> tags to display UML diagrams.# When svg is set to true, diagrams are displayed using <svg /> tags, maintaining functionality like links e.g.# default = falsesvg=true
params:plantuml:enable:truetheme:default# Set url to plantuml server# default is http://www.plantuml.com/plantuml/svg/svg_image_url:'https://www.plantuml.com/plantuml/svg/'# By default the plantuml implementation uses <img /> tags to display UML diagrams.# When svg is set to true, diagrams are displayed using <svg /> tags, maintaining functionality like links e.g.# default = falsesvg:true
To enable/disable MarkMap, update hugo.toml/hugo.yaml/hugo.json:
[params.markmap]enable=true
params:markmap:enable:true
{"params":{"markmap":{"enable":true}}}
Diagrams with Diagrams.net
Diagrams.net (aka draw.io) 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 diagrams.net site to import those images again for edit in the future. With draw.io enabled, Docsy will 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.
Note
If you’re creating a new diagram, be sure to File -> Export in either svg or png format (svg is usually the best choice) and ensure the Include a copy of my diagram is selected so it can be edited again later.
As the diagram data is transported via the browser, the diagrams.net 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!
To enable detection of diagrams, update hugo.toml/hugo.yaml/hugo.json:
[params.drawio]enable=true
params:drawio:enable:true
{"params":{"drawio":{"enable":true}}}
You can also deploy and use your own server for editing diagrams, in which case update the configuration to point to that server:
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, Norwegian, and
Persian. The default language is English:
contentDir="content/en"defaultContentLanguage="en"defaultContentLanguageInSubdir=false...[languages][languages.en]languageName="English"# Weight used for sorting.weight=1[languages.en.params]title="Goldydocs"description="Docsy does docs"[languages.no]languageName="Norsk"contentDir="content/no"[languages.no.params]title="Goldydocs"description="Docsy er operativsystem for skyen"time_format_default="02.01.2006"time_format_blog="02.01.2006"
contentDir:content/endefaultContentLanguage:endefaultContentLanguageInSubdir:false…languages:en:languageName:Englishweight:1# used for sortingparams:title:Docsydescription:Docsy does docs'no':languageName:NorskcontentDir:content/noparams:title:Docsydescription:Docsy er operativsystem for skyentime_format_default:02.01.2006time_format_blog:02.01.2006
{"contentDir":"content/en","defaultContentLanguage":"en","defaultContentLanguageInSubdir":false,"languages":{"en":{"languageName":"English","weight":1,"params":{"title":"Docsy","description":"Docsy does docs"}},"no":{"languageName":"Norsk","contentDir":"content/no","params":{"title":"Docsy","description":"Docsy er operativsystem for skyen","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.
Attention (only when using Docsy as hugo module)
If you have a multi language installation, ensure that the section [languages]
inside your
configuration file
is declared before the section [module] with the module imports. Otherwise
you will run into trouble!
Tip
If there’s any possibility your site might be translated into other languages,
consider creating your site with your content in a language-specific
subdirectory, as it means you don’t need to move it if you add another language.
For adding multiple language versions of other site elements such as button
text, see the internationalization bundles
section below.
Right-to-left languages
Docsy supports top-down Right-To-Left (RTL) languages such as Persian through
Bootstrap’s RTL feature, which uses RTLCSS.
If your multilingual site includes an RTL language (configured with
languageDirection: rtl), then your project needs to include the rtlcss
package. You can add this package to your dev dependencies as follows:
If you configure more than one language in your
configuration file,
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, repository links, 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 Esperanto and create a copy of en.toml called eo.toml), we
recommend you do this in the theme rather than in your own project. You can
then open a
pull request
to contribute your translation to the Docsy community.
Hugo Tip
Run hugo server --printI18nWarnings when doing
translation work, as it will give you warnings on what strings are missing.
Create custom UI strings
If any of the Docsy theme UI strings in your chosen language aren’t suitable for
your project, or if you need additional strings for your site, you can create
your own project-specific internationalization file in your project’s /i18n
directory. For example, if you want to override any of Docsy’s
English-language strings,
create your own /i18n/en.toml with just your custom strings. Any values you
specify in this file will override the theme versions, while the remaining
strings will come from the theme’s corresponding internationalization bundle.
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:
Ensure you have an up to date local copy of your site files cloned from your repo.
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).
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:
Click New site from Git.
Click your chosen Git provider, then choose your site repo from your list of repos.
In the Deploy settings page:
Specify your Build command. The exact build command depends on how you have chosen to use Docsy:
If you are using Docsy as a Git submodule, 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 are using Docsy as a Hugo module or NPM package, you can just specify hugo.
Click Show advanced.
In the Advanced build settings section, click New variable.
Specify NODE_VERSION as the Key for the new variable, and set its Value to the latest LTS version of node.js (minimum recommended version: v20.x).
In the Advanced build settings section, click New variable.
Specify HUGO_VERSION as the Key for the new variable, and set its Value to the latest version of Hugo (minimum recommended version: 0.125.4).
In the Advanced build settings section, click New variable again.
Specify GO_VERSION as the Key for the new variable, and set its Value to the latest version of Go (minimum recommended version: 1.21).
If you don’t want your site to be indexed by search engines, you can add an environment flag to your build command to specify a non-production environment, as described in Build environments and indexing.
Click Deploy site.
Note
Netlify uses your site repo’s package.json file to install any JavaScript dependencies (like postcss) before building your site. If you haven’t just copied our example site’s version of this file, make sure that you’ve specified all our prerequisites.
For example, if you want to use a version of postcss-cli later than version 8.0.0, you need to ensure that your package.json also specifies postcss separately:
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 Focal 20.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.
Deployment on GitHub Pages
If your repo is hosted on GitHub, a simple option is to serve your site with GitHub Pages. GitHub Pages lets you create project, user, and organization sites; for a project site, your site URL will be http(s)://<username>.github.io/<repository_name>, custom domains are also supported. GitHub Pages come with continuous deployment using GitHub actions, while the marketplace for actions has useful tools for spell and link checking, deploy previews, and more. Using your existing GitHub account, you can start by using the free plan for publicly available repositories, with premium tiers available for business use cases.
The Docsy example site repo provides a workflow file that you can use when deploying to GitHub Pages. If you used the example site as template for your new site as described here, you may already have this file in your repo, if not the instructions below show you how to create your own workflow file.
Before deploying on GitHub Pages, make sure that you’ve pushed your site source to your chosen GitHub repo, following any setup instructions in Using the theme.
Correct baseURL setting
Make sure to correctly set your site’s baseURL, either via hugo’s --baseURL '…' command line parameter or inside your your hugo.toml/hugo.yaml/hugo.json configuration file. When deploying to GitHub pages your baseURL needs to be set to https://<USERNAME>.github.io/<repository_name>, otherwise your site layout will be broken.
With GitHub Pages, a site is published to the branch gh-pages and served from there by default. You must create this branch first, either in the GitHub web interface or via command line (at the root of your local repo clone):
$ git checkout -b gh-pages
Switched to a new branch 'gh-pages'
Push this local branch to your repo:
$ git push --set-upstream origin gh-pages
details omitted …
* [new branch] new -> new
branch 'gh-pages' set up to track 'origin/gh-pages'.
Switch back to the main (or work) branch of your repo:
$ git checkout main
Switched to branch 'main'
Check if you already have the workflow file .github/workflows/deploy-github-pages.yml in your repo. If this file doesn’t exist, do the following:
Create a new empty workflow file from the root of your repo, as follows:
Open the file in an editor of your choice, paste in the code below, and save the file:
name:Deployment to GitHub Pageson:workflow_dispatch:push:branches:- main # <-- specify the branch you want to deploy frompull_request:env:REPO_NAME:${{ github.event.repository.name }}REPO_OWNER:${{ github.repository_owner }}jobs:deploy:runs-on:ubuntu-22.04concurrency:group:${{ github.workflow }}-${{ github.ref }}steps:- uses:actions/checkout@v4with:fetch-depth:0# Fetch all history for .GitInfo and .Lastmod- name:Setup Hugouses:peaceiris/actions-hugo@v3with:hugo-version:'0.125.5'extended:true- name:Setup Nodeuses:actions/setup-node@v4with:node-version:'20'cache:'npm'cache-dependency-path:'**/package-lock.json'- run:npm ci- run:hugo --baseURL https://${REPO_OWNER}.github.io/${REPO_NAME} --minify- name:Deployuses:peaceiris/actions-gh-pages@v4if:${{ github.ref == 'refs/heads/main' }}# <-- specify same branch as above herewith:github_token:${{ secrets.GITHUB_TOKEN }}
Add the file to the staging area, commit your change and push the change to your remote GitHub repo:
$ git add .github/workflows/deploy-github-pages.yml
$ git commit -m "Adding workflow file for site deployment"$ git push origin
In your browser, make sure you are logged into your GitHub account. In your repo Settings, select Pages.
Under Build and deployment, select Deploy from a branch in the source dropdown.
From the branch dropdown, select gh-pages as branch where the site is built from.
From the folder dropdown, select /(root) as root directory.
That’s it! Your deployment workflow for your site is configured.
Any future push to the branch specified in your workflow file will now trigger the action workflow defined in the workflow file. Additionally, you can trigger the deployment manually by using GitHub web UI.
Once you push to your repo, you can see the progress of the triggered workflow in the Actions tab of the the GitHub web UI:
After the first successful deployment, a new environment github-pages is added to your repo. This is shown at the right of your repo main view (below Releases and Packages). When you click on this environment, a list of deployments is displayed:
You can find out more in Hosting on GitHub in the Hugo documentation.
For advanced use cases, the hugo-action used inside the workflow file has more configuration options, which are well documented.
Deployment with Amazon S3 + Amazon CloudFront
There are several options for publishing your web site using Amazon Web Services, as described in this blog post. This section describes the most basic option, deploying your site using an S3 bucket and activating the CloudFront CDN (content delivery network) to speed up the delivery of your deployed contents.
After your registration at AWS, create your S3 bucket, connect it with your domain, and add it to the CloudFront CDN. This blog post has all the details and provides easy to follow step-by-step instructions for the whole procedure.
Download and install the latest version 2 of the AWS Command Line Interface (CLI). Then configure your CLI instance by issuing the command aws configure (make sure you have your AWS Access Key ID and your AWS Secret Access Key at hand):
$ aws configure
AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE
AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Default region name [None]: eu-central-1
Default output format [None]:
Check the proper configuration of your AWS CLI by issuing the command aws s3 ls, this should output a list of your S3 bucket(s).
Inside your hugo.toml/hugo.yaml/hugo.json, add a [deployment] section like this one:
Run the command hugo --gc --minify to render the site’s assets into the public/ directory of your Hugo build environment.
Use Hugo’s built-in deploy command to deploy the site to S3:
hugo deploy
Deploying to target "aws" (www.your-domain.tld)
Identified 77 file(s) to upload, totaling 5.3 MB, and 0 file(s) to delete.
Success!
Invalidating CloudFront CDN...
Success!
As you can see, issuing the hugo deploy command automatically invalidates your CloudFront CDN cache.
That’s all you need to do! From now on, you can easily deploy to your S3 bucket using Hugo’s built-in deploycommand!
For more information about the Hugo deploy command, including command line options, see this synopsis. In particular, you may find the --maxDeletes int option or the --force option (which forces upload of all files) useful.
Automated deployment with GitHub actions
If the source of your site lives in a GitHub repository, you can use GitHub Actions to deploy the site to your S3 bucket as soon as you commit changes to your GitHub repo. Setup of this workflow is described in this blog post.
Handling aliases
If you are using aliases for URL management, you should have a look at this blog post. It explains how to turn aliases into proper 301 redirects when using Amazon S3.
If S3 does not meet your needs, consider AWS Amplify Console. This is a more advanced continuous deployment (CD) platform with built-in support for the Hugo static site generator. A starter can be found in Hugo’s official docs.
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!
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 Hugo Module or
Git submodule), you can easily update the Docsy theme in your site yourself. If
you have cloned the theme itself into your own project you can also update,
though you may need to resolve merge conflicts.
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 since your last update, see the list of
Docsy commits.
If you have been using the theme as a Git submodule, you can also update your
site to use Docsy as a Hugo Module. This
is the latest and simplest way to pull in a Hugo theme from its repository. If
you’re not ready to migrate to Hugo Modules yet, don’t worry, your site will
still work and you can continue to update your submodule as before.
6.1 - Update your Docsy Hugo Module
Update your Docsy theme to the latest version using Hugo Modules.
When using the Docsy theme as a Hugo Module, updating your theme is really easy.
At the command prompt, change to the root directory of your existing site.
cd /path/to/my-existing-site
Then invoke hugo’s module get subcommand with the update flag:
hugo mod get -u github.com/google/docsy
Hugo automatically pulls in the latest theme version. That’s it, your update is
done!
Tip
If you want to set your module to a certain version inside the Docsy theme repo,
simply specify the name of the tag representing this version when updating your
theme, for example:
hugo mod get -u github.com/google/docsy@v0.11.0
Instead of a version tag, you can also specify a commit hash, for example:
hugo mod get -u github.com/google/docsy@6c8a3afe
6.2 - Update Docsy without Hugo Modules
Update the Docsy theme to the latest version using submodules or git pull.
If you aren’t using Hugo Modules, depending on how you chose to install Docsy on your existing site, use one of the following two procedures to update your theme.
Push the commit to your project repo. For example, run:
git push origin master
Route 2: Update your Docsy clone
If you cloned the Docsy theme into
the themes folder in your project, then you use the git pull command:
Navigate to the themes directory in your local project:
cd themes
Ensure that origin is set to https://github.com/google/docsy.git:
git remote -v
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.
6.3 - Migrate to Hugo Modules
Convert an existing site to use Docsy as a Hugo Module
TL;DR: Conversion for the impatient expert
Run the following from the command line:
cd /path/to/my-existing-site
hugo mod init github.com/me-at-github/my-existing-site
hugo mod get github.com/google/docsy@v0.11.0
sed -i '/theme = \["docsy"\]/d' config.toml
mv config.toml hugo.toml
cat >> hugo.toml <<EOL
[module]
proxy = "direct"
[[module.imports]]
path = "github.com/google/docsy"
EOLhugo server
cd my-existing-site
hugo mod init github.com/me-at-github/my-existing-site
hugo mod get github.com/google/docsy@v0.11.0
findstr /v /c:"theme = [\"docsy\"]" config.toml > hugo.toml
(echo [module]^
proxy = "direct"^
[[module.imports]]^
path = "github.com/google/docsy")>>hugo.toml
hugo server
Detailed conversion instructions
Import the Docsy theme module as a dependency of your site
At the command prompt, change to the root directory of your existing site.
cd /path/to/my-existing-site
Only sites that are Hugo Modules themselves can import other Hugo Modules. Turn your existing site into a Hugo Module by running the following command from your site directory, replacing github.com/me/my-existing-site with your site repository:
hugo mod init github.com/me/my-existing-site
This creates two new files, go.mod for the module definitions and go.sum which holds the checksums for module verification.
Next declare the Docsy theme module as a dependency for your site.
hugo mod get github.com/google/docsy@v0.11.0
This command adds the docsy theme module to your definition file go.mod.
Update your config file
In your hugo.toml/hugo.yaml/hugo.json file, update the theme setting to use Hugo Modules. Find the following line:
theme=["docsy"]
theme:docsy
"theme":"docsy"
Change this line to:
theme=["github.com/google/docsy"]
theme:- github.com/google/docsy
"theme":["github.com/google/docsy"]
Alternatively, you can omit this line altogether and replace it with the settings given in the following snippet:
[module]proxy="direct"# uncomment line below for temporary local development of module# replacements = "github.com/google/docsy -> ../../docsy"[module.hugoVersion]extended=truemin="0.73.0"[[module.imports]]path="github.com/google/docsy"disable=false
You can find details of what these configuration settings do in the Hugo modules documentation.
Depending on your environment you may need to tweak them slightly, for example by adding a proxy to use when downloading remote modules.
Tip
In Hugo 0.110.0 the default config base filename was changed to hugo.toml.
If you are using hugo 0.110 or above, we recommend renaming your config.toml to hugo.toml!
Attention
If you have a multi language installation, please make sure that the section [languages] inside your hugo.toml is declared before the section [module] with the module imports. Otherwise you will run into trouble!
Check validity of your configuration settings
To make sure that your configuration settings are correct, run the command hugo mod graph which prints a module dependency graph:
hugo mod graph
hugo: collected modules in 1092 ms
github.com/me/my-existing-site github.com/google/docsy@v0.11.0
github.com/google/docsy@v0.11.0 github.com/twbs/bootstrap@v5.2.3+incompatible
github.com/google/docsy@v0.11.0 github.com/FortAwesome/Font-Awesome@ v0.0.0-20230802202706-f0c25837a3fe
Make sure that three lines with dependencies docsy, bootstrap and Font-Awesome are listed. If not, please double check your config settings.
Tip
In order to clean up your module cache, issue the command hugo mod clean
hugo mod clean
hugo: collected modules in 995 ms
hugo: cleaned module cache for"github.com/FortAwesome/Font-Awesome"hugo: cleaned module cache for"github.com/google/docsy"hugo: cleaned module cache for"github.com/twbs/bootstrap"
Clean up your repository
Since your site now uses Hugo Modules, you can remove docsy from the themes directory, as instructed below.
First, change to the root directory of your site:
cd /path/to/my-existing-site
Previous use of Docsy theme as git clone
Simply remove the subdirectory docsy inside your themes directory:
rm -rf themes/docsy
Previous use of Docsy theme as git submodule
If your Docsy theme was installed as submodule, use git’s rm subcommand to remove the subdirectory docsy inside your themes directory:
git rm -rf themes/docsy
You are now ready to commit your changes to your repository:
git commit -m "Removed docsy git submodule"
Attention
Be careful when using the rm -rf command, make sure that you don’t inadvertently delete any productive data files!
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 this page provides some useful tips and
potential gotchas for adding and editing content for your site. Feel free to add your own!
Linking
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/sub-file.md) 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 "filename.md" >}} link in Hugo will actually
find and automatically link to your file named filename.md.
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/.
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.
Tip
If you want to copy this guide, be aware that its source files are inside the Docsy theme repo, and so it doesn’t have its own themes/ directory: instead, we run hugo server --themesDir ../.. to use Docsy from its parent directory. You may want to either copy the site and add a themes/ directory with Docsy, or just copy the docs/ folder into your existing site’s content root.
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.
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 https://cla.developers.google.com/ 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.
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
Fork the Docsy repo on GitHub: this site’s files live in the userguide subdirectory.
Make your changes and send a pull request (PR).
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.)
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!
Click Details to the right of “Deploy preview ready” to see a preview
of your updates.
Continue updating your doc and pushing your changes until you’re happy with
the content.
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:
Click Edit this page in the top right hand corner of the page.
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.
If you want to run your own local Hugo server to preview your changes as you work:
Follow the instructions in Getting started to install Hugo and any other tools you need.
Fork the Docsy repo into your own project, then create a local copy using git clone:
git clone https://github.com/google/docsy.git
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.
Continue with the usual GitHub workflow to edit files, commit them, push the
changes up to your fork, and create a pull request.
Preview your changes using a Docker container
Docsy comes with Dockerfile and docker-compose files to run the server
locally with Docker, without installing any additional dependencies.
Open http://localhost:1313 in your web browser to load the docsy user guide.
In most cases, docsy will automatically reload the site to reflect any changes
to the documentation or the code. Changes to some parts of the docsy code may
require manually reloading the page or re-starting the container.
Press Ctrl + C to stop the container.
User guide formatting
We use Prettier to format the markdown source of the User
Guide. To to check the formatting of your documentation changes, use the
following command:
npm run check:format
To automatically fix formatting issues, run npm run fix:format.
Prettier doesn’t currently understand Hugo template language directives,
so you might need to bracket such directives using the following ignore
directives:
You can use these ignore directives to surround any markdown that you’d like
Prettier to ignore. If the region is a contiguous block of text, then you can
omit the end directive and replace the start directive with
prettier-ignore-start.
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.
Welcome!
Karibu sana!
