Content authoring

Write website docs, translations, shortcodes, and UI strings for vanityURLs.link.

Use this page when you add or update website content in content/, i18n/, data/, or Hugo layouts/.

Repository areas

Content files

Use language-specific filenames:

brand-content/web-site/content-authoring.en.md
brand-content/web-site/content-authoring.fr.md

Hugo pairs translations when the base filename and directory match. A language switcher may fall back to the language root when a sibling translation is missing.

Add a documentation page

Create a page in the matching section:

hugo new web-site/example.en.md --config hugo.brand.yml

Then set front matter:

---
aside: false
title: "Example"
description: "Short description for SEO and social cards."
weight: 30
---

Documentation navigation is section-driven. The section _index controls where the section appears, and each page weight controls the page order inside that section.

Add a blog post

hugo new blog/my-new-post.en.md

Use front matter like:

---
title: "My new post"
description: "Short description for search and social cards."
date: 2026-06-03
tags: [hugo, cloudflare]
draft: true
---

Create the French translation as content/blog/my-new-post.fr.md when the translated content is ready.

Add UI text

Add template labels to both i18n files:

# i18n/en.yml
my_new_string: "Continue"

# i18n/fr.yml
my_new_string: "Continuer"

Use it in a template with:

{{ i18n "my_new_string" }}

Use shortcodes

Common documentation shortcodes include:

{{< callout type="warning" title="Breaking change" >}}
This option was removed in v3.
{{< /callout >}}

{{< details title="Why this matters" >}}
Longer explanation that should stay available without taking over the page.
{{< /details >}}

{{< cards cols="3" >}}
{{< card title="Setup" icon="download" href="/docs/setup/" >}}
Start here.
{{< /card >}}
{{< /cards >}}

Use callouts for operational warnings, safety limits, first-time setup notes, and versioned behavior changes. Keep ordinary explanatory paragraphs as prose.

Page images

Keep images beside the page or blog post they support when possible. This keeps the Markdown and its media together when the content moves, and makes it easier to review page-specific assets.

For a blog post with local images, create a page bundle by moving the Markdown file into a directory and renaming it _index.md:

content/blog/my-new-post/
├── _index.en.md
├── _index.fr.md
└── hero.png

Then reference the image with a relative Markdown path:

![Alt text](hero.png)

Use static/ when an image needs a stable public URL, is shared across many pages, or must be referenced outside the content bundle:

static/images/docs/cloudflare-dashboard.png

Reference static images from the site root:

![Alt text](/images/docs/cloudflare-dashboard.png)

Assets

Use assets/ when Hugo should process, fingerprint, or bundle a file. Use static/ for files that need a stable URL.

flowchart LR
A[New file
or old URL]
B{Should Hugo process
or fingerprint it?}
C[Use assets]
D{Needs a stable
public path?}
E[Use static]
F{Moved
content
page?}
G[Use front
matter aliases]
H[Keep beside
the page bundle]

A --> B
B -->|Yes| C
B -->|No| D
D -->|Yes| E
D -->|No| F
F -->|Yes| G
F -->|No| H

Use static/_redirects for redirect rules that belong in a fixed static file. It is not the only redirect mechanism: content pages can also define aliases in front matter when an old URL should redirect to a moved page.

Before publishing

Run:

npm run build
npm run lint

Use npm run lint:all when the change affects many links, navigation, or generated HTML.

When the content change is ready to commit, use the Commit style guidance so release-please can classify the work correctly.