Writing pages
This page covers the complete process for writing a documentation page. It explains file location, front matter, heading anchors, links, images, drafts, and page-end controls. The site must already build locally. If it does not, start with Quick start.
Creating a page
A page is a Markdown file under content/. Its location determines its URL.
For example, content/docs/install.md is published as /docs/install/. The Chinese
translation is a .zh.md file of the same name in the same directory, sharing
one logical path with the English page.
Use a single file for a page without attached resources. If a page has images,
cast files, or example configuration, create a directory. Name the page file
index.md and put the resources beside it. Hugo calls this a
page bundle:
the two page shapes inside content/
content/
docs/
- _index.mdsection index, English
- _index.zh.mdsection index, Chinese
- install.mdsingle-file page → /docs/install/
- install.zh.mdits Chinese translation
anatomy/page bundle → /docs/anatomy/
- index.md
- index.zh.md
- shell.webppage resource, shared by both languages
hugo new content docs/install.md generates an empty file with front matter
from an archetype. See the Hugo documentation.
You can also write the file manually.
When a Chinese page has no English counterpart, Hugo does not give it
resources without a language suffix. In that case the resource filename
needs the .zh. infix (shell.zh.webp) while the body still writes
shell.webp.
The front matter you need
Between the two --- lines at the top of the file is YAML front matter. Four
keys belong on every page:
Use description to state in one sentence what the reader can accomplish.
It appears on section index cards, in search results, and on social cards.
weight determines sidebar order. Only equal weights use alphabetical order.
Other keys are optional. These include the icon, draft status, search weight, comment switch, and page shell. For the full table, see Page parameters.
Heading levels and stable anchors
Start body sections at ##. Reserve # for title. The theme renders the page
heading. Another # in the body creates a second top-level heading. The right
column outline starts at ##. Hugo’s markup.tableOfContents determines its
maximum depth. This site uses ####.
Write an explicit English anchor {#id} on every ## and ###:
There are two reasons:
- Cross-language alignment. Hugo derives an ID from heading text. A Chinese heading produces a Chinese ID.
/docs/install/#prerequisitesand/zh/docs/install/#前提条件identify equivalent places with different anchors. A translation audit cannot compare them. Give the translated heading the English page’s ID. Both pages then share one fragment. - Link stability. Revisions can change heading text. They should not break public links. After publication, an explicit ID is a public route. If you must rename it, leave an empty anchor for the old ID:
Use lowercase English with hyphens, unique within the page. This site’s translation audit compares the heading IDs rendered by the English and Chinese pages and fails on a mismatch.
Writing links
Use one of these three forms, according to its purpose:
| Form | Example | When to use it |
|---|---|---|
| Absolute site path | [Configuration](/docs/customize/config/) |
The default. It points at a published route, is easy to audit and replace site-wide, and survives source files moving |
| Relative path | [another page](../organize/),  |
Resources inside the same page bundle, or a neighboring page that should follow the source directory |
The ref / relref shortcode |
[Configuration]({{< ref "/docs/configure/overview" >}}) |
If the target must exist at build time. A missing target fails the build instead of leaving a broken link |
All three carry a trailing slash and point at directory-style routes
(/docs/write/pages/), matching Hugo’s default permalinks.
The theme has no link render hook. It passes links to Goldmark unchanged.
External links do not automatically receive target="_blank". If you need a
new tab, write HTML or use the site’s layouts/_markup/render-link.html.
Plain Markdown links are not checked for target existence. Use these rules:
- Prefer absolute paths for internal links. After restructuring the site, use
grepto replace them site-wide. - When you move a page, add
aliasesfor the old path. Update internal links to the new route. Do not use an alias for navigation indefinitely. - If you are unsure that a target exists, use
ref. The build then checks it.
In a bilingual site, link to the logical page (/docs/write/pages/) rather than
to a .zh.md filename, and keep fragment IDs language-neutral.
Where images go
Put a page’s screenshots in its page bundle. Put shared images in
assets/images/. Put large files that require no processing in static/.
Use  for all three. An attribute line controls caption,
size, zoom, and numbering. See Images.
Drafts and publishing
A page with draft: true never reaches the build output:
Preview with hugo server -D to show drafts (-D is --buildDrafts). A page
whose date is in the future is also excluded. -F shows those pages. A production
build uses neither switch, and plain hugo publishes only finished content.
OINK’s Markdown extensions
The body is standard Markdown (Goldmark) plus the native forms below. Each is ordinary Markdown syntax with one attribute line, and each stays readable as source on GitHub:
| Component | Shortest syntax | Page |
|---|---|---|
| Callouts | > [!NOTE] on the first line of a blockquote |
Callouts |
| Tabs | Two adjacent fences each carrying {tab="Homebrew"} |
Tabs |
| Steps | An ordered list followed by a {.steps} line |
Steps |
| Cards | A list of links followed by a {.cards} line |
Cards |
| Field lists | A table followed by {.fields meta="type default"} |
Fields |
| Table extras | A table followed by {.matrix} or {caption="…"} |
Tables |
| Code blocks | {title="hugo.yml" copy=false} on the fence info line |
Code Blocks |
| Images | A standalone image followed by {caption="…" width="600"} |
Images |
| File trees | A filetree fence, one - name/ # comment per line |
FileTree |
| Mathematics | A math fence, or display math wrapped in $$ |
Math |
| Diagrams | A mermaid fence (also plantuml, markmap, echarts) |
Mermaid |
The remaining components use shortcodes. These include badges, keys, file includes, terminal recordings, and the Book figure and table family. For syntax and parameters, see Components.
A combined example: code fences and a callout inside steps.
- Install Hugo Extended, 0.168.0 at the oldest:
- Clone OINK Starter and preview it:
Tip
Add
-Dto preview drafts as well.
What appears at the end of a page
The theme generates these four blocks in a fixed order. Do not write them in the body. An optional Share bar appears before them:
| Position | What it is | Default | Where to configure |
|---|---|---|---|
| 1 | Feedback: the two “Was this page helpful?” buttons | Off | Repository links and page info |
| 2 | Last modified: the time and the most recent commit subject, linked to GitHub | On when Git information is available | Repository links and page info |
| 3 | Pager: previous and next, in sidebar tree order | On for docs / book / blog | Navigation and menus |
| 4 | Comments: giscus | When configured and enabled | Comments |
The theme also generates the action menu beside the title. It includes copy Markdown, edit this page, view history, open an issue, and print. Configure it in Repository links and page info.
To turn off a control for one page, set its front matter: feedback: false,
annotation: false, pager: false, comments: false. The keys are described
in Page parameters.
Verify
After writing a page, run a production build:
- The build must exit with
Total in …and no ERROR. An invalid attribute key or component parameter logs a warning with a source position and renders a safe fallback, whereas arefpointing to a missing target fails the build. --printPathWarningsflags any two pages that resolve to the same output path, which is most common in multilingual sites or after editingpermalinks.
Then confirm three things in the browser:
- The page appears in the sidebar at the position determined by
weight. - The right-hand outline lists your
##headings. Clicking a heading adds an English anchor to the URL. - The English and Chinese versions of the same heading share an anchor (this site audits that with
node scripts/check-doc-translations.mjs --public public).
Related
- Organizing content — how the directory structure decides the sidebar
- Page parameters — the full front matter table
- Components — each component’s syntax and parameters
- Languages — paired bilingual files and fallback for untranslated pages
- Local preview — the
hugo serverswitches worth knowing