hugodoks

hint

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

hint renders a titled callout box with a Markdown body. Give the style alone, positionally, or the style and a title by name:

{{< hint warning >}}Something that can bite if ignored.{{< /hint >}}

{{< hint style="tip" title="Best practice" >}}The recommended way.{{< /hint >}}

Shortcode parameters are either all positional or all named, so a custom title needs style="…" too. Styles: info (default), note, tip, warning, danger, success; unknown styles fall back to info. The title defaults to the style’s name.

Your first docs site

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

The fastest path from zero to a rendered docs page.

Mount the theme

hugo mod init example.com/mydocs
hugo mod get github.com/fernandezvara/hugodoks

# hugo.toml
[module]
 [[module.imports]]
 path = "github.com/fernandezvara/hugodoks"

[outputs]
 home = ["html", "rss", "searchindex"]

Add content

hugo new docs/_index.md
hugo new docs/getting-started.md

Serve

hugo server

The sidebar shows both Guides and Shortcodes as collapsible groups — opening one collapses the other.

button

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

button renders a link as a Pico role="button" element. Named params: href, style (secondary or contrast), icon and the outline="true" flag. External links get rel="noopener" automatically.

Get started Back to the gallery hugodoks on GitHub

Source

{{< button href="../getting-started/" icon="rocket-launch" >}}Get started{{< /button >}}

{{< button href="../shortcodes/" style="secondary" outline="true" >}}Back to the gallery{{< /button >}}

{{< button href="https://github.com/fernandezvara/hugodoks" style="contrast" icon="code" >}}hugodoks on GitHub{{< /button >}}

pagelink

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

pagelink takes a content path (positional or page=) and renders a card with the target’s icon, title and description. Because it resolves through site.GetPage, a typo warns at build time instead of 404ing your readers.

Getting started

Install hugodoks in a new Hugo project and publish your first docs page.

Configuration

Site params, menus and build settings hugodoks understands.

Source

{{< pagelink "/docs/getting-started" >}}

{{< pagelink page="/docs/configuration" >}}

columns

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

columns wraps column children in Pico’s .grid — equal-width columns on desktop that stack under 768px.

Left column

Markdown works in here
Lists, code, other shortcodes

Middle column

Each column is an equal share of the row.

Right column

hugo server --bind 0.0.0.0

Source

{{< columns >}}
 {{< column >}}
 **Left column**
 {{< /column >}}
 {{< column >}}
 **Right column**
 {{< /column >}}
{{< /columns >}}

steps

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

steps wraps a Markdown ordered list and renders it with large accent step markers — use it for install procedures and tutorials.

Create the site — hugo new site my-docs
Add the theme — import github.com/fernandezvara/hugodoks as a Hugo module
Configure outputs — add searchindex to outputs.home
Write docs — pages under content/docs/ appear in the sidebar
Ship it — hugo --gc --minify

Source

{{< steps >}}
1. **Create the site** — `hugo new site my-docs`
2. **Add the theme** — import `github.com/fernandezvara/hugodoks`
{{< /steps >}}

tabs

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

tabs groups tab children into keyboard-accessible tabbed panels. Each tab takes its title as the first positional parameter (or title=). Panels hold any Markdown, including code blocks.

[module]
 [[module.imports]]
 path = "github.com/fernandezvara/hugodoks"

git submodule add https://github.com/fernandezvara/hugodoks themes/hugodoks

theme = "hugodoks"

docker run --rm -v "$PWD:/src" -w /src \
 docker.io/hugomods/hugo:exts hugo server --bind 0.0.0.0

Source

{{< tabs >}}
 {{< tab "Hugo module" >}}
 ```toml
 path = "github.com/fernandezvara/hugodoks"
 ```
 {{< /tab >}}
 {{< tab "Git submodule" >}}
 theme = "hugodoks"
 {{< /tab >}}
{{< /tabs >}}

annotated

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

annotated renders a code block with a numbered annotation list beneath it in a <figcaption>. Split code from notes with  — the ordered list becomes the caption.

[outputs]
 home = ["html", "rss", "searchindex"]

[markup.highlight]
 noClasses = false

searchindex emits /index.json, the data source for the search modal. Hugo never merges outputs from a theme — declare it yourself.
Class-based highlighting lets the theme’s light/dark code stylesheets apply; the default inline styles would ignore the theme toggle.

Source

{{< annotated >}}
```toml
noClasses = false
```
<!-- annotations -->
1. The note for this code.
2. Another note.
{{< /annotated >}}

types

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

types renders pipe-separated values as a row of code badges — for parameter signatures, front-matter reference tables and return types.

Accepted values for params.docs.repoBranch:

string "main" "develop"

A hint’s style positional parameter:

info warning danger success

Source

{{< types >}}string | "main" | "develop"{{< /types >}}

paramcallout

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

paramcallout renders its body as a linked callout only when the named site param is set — the link points at the param’s value. It’s the page-level counterpart of the landing banner’s only_when_param.

Use it for “a live demo is running” notes on pages that describe one: deploy previews inject the URL at build time, and the callout simply isn’t there in builds without it.

Info

Nothing rendered above? That’s the feature working: this build has no exampleurl param. Rebuild with HUGO_PARAMS_EXAMPLEURL="https://example.com" to see it — the theme’s own test suite asserts both cases.

Source

{{< paramcallout param="exampleurl" icon="squares-four" >}}
A live deployment was configured for this build — open it
{{< /paramcallout >}}

Named params: param (the site param to check, required) and icon.

Getting started

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

This guide takes a brand-new Hugo project to a running documentation site in a few minutes.

Requirements

Hugo Extended >= 0.154.0 — check with hugo version. The theme needs the extended edition for its asset pipeline.
Git and Go — only if you install the theme as a Hugo module (recommended below).

Info

No Hugo installed? The theme repository itself is dockerized — inside a clone of hugodoks, make serve runs this site at http://localhost:1313 with the hugomods/hugo:exts image and nothing installed locally.

1. Create a site

hugo new site my-docs
cd my-docs

2. Add the theme

Initialize the site as a Go module, then import the theme in hugo.toml:

icons

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

icons renders every glyph in the theme’s vendored Phosphor font (regular weight) with its name — no network needed. Use any name below wherever the theme accepts an icon:

icon: front matter — sidebar nav and section cards.
params.brand.icon — next to the site title.
params.docs.aiAssistIcon — the “Ask AI” dropdown button.
Shortcodes — icon parameter on button, pagelink, paramcallout; landing icon: fields.
Templates — {{ partial "hd-icon.html" "rocket-launch" }} renders <i class="ph ph-rocket-launch hd-icon">.

Unknown names render a blank glyph — there is no fallback.

Configuration

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

Everything below goes in your site’s hugo.toml (or the YAML/JSON equivalent). The complete working example is this site’s own hugo.toml.

Required build settings

[outputs]
 home = ["html", "rss", "searchindex"]

[markup.highlight]
 noClasses = false

outputs.home — Hugo does not merge outputs from a theme. searchindex emits /index.json, the data source for the search modal; rss enables the RSS feed linked in <head>. Omit searchindex and the search trigger quietly does nothing.
markup.highlight.noClasses = false — makes Chroma emit CSS classes so the theme’s light/dark-scoped code stylesheets apply. With the default true, every code block is frozen to inline Monokai colors.

Site params

Param	Default	Purpose
`params.description`	—	Fallback `<meta name="description">` for pages without their own `description`
`params.docs.navRoot`	`/docs`	Section used as the root of the left sidebar nav
`params.docs.navDefaultIcon`	`dot`	Fallback sidebar icon for pages without `icon` in front matter (`""` renders an empty slot)
`params.docs.editPage`	`false`	Show an “Edit this page” link under each docs article
`params.docs.lastMod`	`false`	Show a “Last updated” line (Git date when `enableGitInfo` is on)
`params.docs.repoURL`	—	Repository base URL for the edit link (GitHub, GitLab and Bitbucket layouts are detected)
`params.docs.repoBranch`	`main`	Branch used in edit links
`params.docs.repoContentDir`	`content`	Directory inside the repo that holds content files
`params.docs.aiAssist`	`false`	Show an “Ask AI” dropdown in docs article headers with prefilled ChatGPT/Claude links to the page
`params.docs.aiAssistIcon`	—	Icon in the dropdown button: a Phosphor name (e.g. `sparkle`)
`params.docs.aiAssistLabel`	“Ask AI”	Text of the dropdown button
`params.brand.icon`	—	Optional icon next to the site title: a Phosphor name (e.g. `book`) or a path to an `.svg` in `assets/`
`params.footer.copyright`	—	Footer line, rendered as Markdown
`params.social.github`	—	`owner/repo` shown on the home page

Example:

Landing page

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

The home page is assembled from sections declared in data/landing.yaml. Each section picks a partial via template, is toggled with enable, and ordered by weight:

sections:
 hero:
 enable: true
 weight: 10
 template: hero
 # …section-specific fields

Delete the file — or set every enable: false — and the home page falls back to rendering content/_index.md as a plain article.

Hero

A badge, a title, a Markdown subtitle, a row of call-to-action buttons and an info line:

Features

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

A tour of what hugodoks renders for every docs site, and the switches that control it.

Pages under params.docs.navRoot (default /docs) become the left sidebar:

Leaf pages and sections sort by weight; a page’s icon shows next to its title. Pages without one get a fallback marker — params.docs.navDefaultIcon (default dot; set "" for an empty slot).
Directories with _index.md render as collapsible <details> groups that auto-open on the active page. The section title links to its _index page; the caret toggles the group. Sibling groups stay open independently, like a file browser, and each group’s open state persists in localStorage across page loads.
The current page is highlighted and marked aria-current="page".
Below 768px the sidebar becomes an off-canvas drawer opened by the header’s hamburger button.

With toc: true in front matter, a sticky “On this page” aside is built from the page’s h2–h3 headings (configure the range with markup.tableOfContents.startLevel/endLevel). The toggle button collapses it and remembers the choice across pages via localStorage.

hugodoks

hint

Your first docs site

Mount the theme

Add content

Serve

button

Source

pagelink

Source

columns

Source

steps

Source

tabs

Source

annotated

Source

types

Source

paramcallout

Source

Getting started

Requirements

1. Create a site

2. Add the theme

icons

Configuration

Required build settings

Site params

Landing page

Hero

Features

Sidebar navigation

Table of contents

hugodoks

hint

Your first docs site

Mount the theme#

Add content#

Serve#

button

Source#

pagelink

Source#

columns

Source#

steps

Source#

tabs

Source#

annotated

Source#

types

Source#

paramcallout

Source#

Getting started

Requirements#

1. Create a site#

2. Add the theme#

icons

Configuration

Required build settings#

Site params#

Landing page

Hero#

Features

Sidebar navigation#

Table of contents#

Mount the theme

Add content

Serve

Source

Source

Source

Source

Source

Source

Source

Source

Requirements

1. Create a site

2. Add the theme

Required build settings

Site params

Hero

Sidebar navigation

Table of contents