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.

Look and Feel

Thu, 05 Jan 2017 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

Thu, 05 Jan 2017 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.

Search

Thu, 05 Jan 2017 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.

Doc Versioning

Sun, 02 Feb 2020 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:

Docsy Shortcodes

Thu, 05 Jan 2017 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.

Logos and Images

Thu, 05 Jan 2017 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.

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.

Analytics, User Feedback, and SEO

Wed, 05 Jun 2019 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).

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.

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

Diagrams and Formulae

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

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 is embedded into Hugo as of Hugo version v0.132.0.

Content and Customization on Docsy

Adding Content

Content root directory

Look and Feel

Navigation and Menus

Site navbar

Search

Doc Versioning

Adding a version drop-down menu

Docsy Shortcodes

Logos and Images

Add your logo

Print Support

Analytics, User Feedback, and SEO

Adding Analytics

Prerequisites

Repository Links and other page information

Taxonomy Support

Terminology

Diagrams and Formulae

LaTeX support with KaTeX