Content and Customization on Docsy

Adding Content

Mon, 01 Jan 0001 00:00:00 +0000

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.

AI-agent support

Mon, 01 Jan 0001 00:00:00 +0000

Early evaluation

Features described in this page are experimental, and are useful for early adoption and evaluation. Output details and validation coverage may change in future releases. To track the phased evolution of the agent-support feature, see Improve support for AI-agent doc consumption #2614.

Features

When your site opts in, these are the user-facing and machine-readable behaviors Docsy enables:

Markdown output format support. Your project’s outputs configuration controls which page kinds publish Markdown.
Discovery: alternate links and a hidden in-body directive lead agents to each page’s Markdown version and to llms.txt.
View Markdown: page meta area includes a View Markdown link to the Markdown version of the page.
llms.txt: per-language site index of links to Markdown content.

The remainder of this page explains how to enable each feature, and discusses validation and metrics supported with examples.

Analytics, User Feedback, and SEO

Mon, 01 Jan 0001 00:00:00 +0000

Adding Analytics

The Docsy theme builds upon Hugo’s support for Google Analytics, which Hugo provides through embedded templates. Once you set up analytics as described below, usage information for your site (such as page views) is sent to your Google Analytics account.

Prerequisites

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

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Docsy’s settings live under params in your site’s Hugo configuration, each documented with its feature. params.docsy is the namespace Docsy reserves for its own settings; its plugin registry lives there, and older parameters stay where they are.

Theme defaults and your overrides

The defaults Docsy sets in configuration live in its own hugo.yaml. Under Hugo’s default deep-merge strategy for params, maps merge recursively, so you set only the leaves you change; a list or a scalar replaces the theme’s value rather than combining with it. Any Hugo module you import contributes its params the same way, and your project’s values win. For the strategies, see Hugo’s configuration merge; setting params._merge: shallow discards the theme’s entries under any key you also define.

Diagrams and Formulae

Mon, 01 Jan 0001 00:00:00 +0000

Pinned script-dependency versions

Docsy renders some rich content with scripts and stylesheets fetched from public CDNs, at build time or in the browser: Mermaid, KaTeX’s stylesheet and fonts, markmap-autoloader, and Redoc (the redoc shortcode). Each loads at a version pinned in the theme’s configuration and bumped with each Docsy release. Pinning keeps builds reproducible and page rendering stable, and narrows exposure to bad upstream publishes: a version alias such as latest, or a partial version such as 11, is re-resolved by the CDN on each request or uncached build, so your site’s rendering could change or break without any change on your part (for example, when an upstream major ships).

Logos and Images

Mon, 01 Jan 0001 00:00:00 +0000

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:

[params.ui]
navbar_logo = false

params:
 ui:
 navbar_logo: false

{
 "params": {
 "ui": {
 "navbar_logo": false
 }
 }
}

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

Look and Feel

Mon, 01 Jan 0001 00:00:00 +0000

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.

Navigation and Menus

Mon, 01 Jan 0001 00:00:00 +0000

Docsy provides multiple built-in navigation features for your sites, including site menus, side navs, and page table of contents (TOC). This page shows you how they work and how to configure and customize them to meet your needs.

A site navbar appears at the top of every site page. It is built from Hugo menus and Docsy-generated elements. Hugo menus consist of an array of menu entries, accessible via the .Site.Menus site variable.

Plugins

Mon, 01 Jan 0001 00:00:00 +0000

Docsy loads some of its optional JavaScript features, and any script you add, as plugins: entries under params.docsy.plugins in your site configuration.

Configure Docsy’s plugins

Plugin	What it does (Default / Loads on)	Learn more
`click-to-copy`	Adds a copy button to code blocks (On, but off under Prism, which has its own / Every page)	Copy to clipboard
`tabpane-persist`	Remembers the selected tab across pages (On / Every page (why))	`tabpane`
`markmap`	Renders `markmap` code blocks as mind maps (Off / Pages with a `markmap` code block)	Activating MarkMap support

To turn a plugin off, set its enable field to false:

Print Support

Mon, 01 Jan 0001 00:00:00 +0000

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.

Repository Links and other page information

Mon, 01 Jan 0001 00:00:00 +0000

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.

Search

Mon, 01 Jan 0001 00:00:00 +0000

Docsy offers multiple options that let your readers search your site content, so you can pick one that suits your needs or design your own. 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 sidebar 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.

Docsy Shortcodes

Mon, 01 Jan 0001 00:00:00 +0000

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.

Taxonomy Support

Mon, 01 Jan 0001 00:00:00 +0000

Docsy supports Hugo 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

Versioning

Mon, 01 Jan 0001 00:00:00 +0000

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.

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

Content and Customization on Docsy

Adding Content

Content root directory

AI-agent support

Features

Analytics, User Feedback, and SEO

Adding Analytics

Prerequisites

Configuration

Theme defaults and your overrides

Diagrams and Formulae

Pinned script-dependency versions

Logos and Images

Add your logo

Look and Feel

Navigation and Menus

Site navbar

Plugins

Configure Docsy’s plugins

Print Support

Repository Links and other page information

Search

Docsy Shortcodes

Taxonomy Support

Terminology

Versioning

Adding a version drop-down menu