Titles, LinkTitles, and Identifiers

One of the most important components of a technical resource is its title.

For Chainguard Academy, there are actually two titles you need to consider:

• The title itself. This is the title that appears at the top of the resource's page and shows up in search engine results.
• The linkTitle. A linkTitle is a Hugo feature that allows you to define a shorter version of a page's title. If defined, this is what will appear in the left-hand navigation menu.

Both titles and linkTitles are defined in a resource's front matter. Here, we'll dig into best practices and guidelines for creating each.

Titles

Per the SEO Guidelines from Write the Docs, documentation should have "imperative, user-centric, goal-oriented headings." Likewise, a title should clearly convey the resource's purpose and goals using action-oriented language centered on the reader.

For example, a title like "Chainguard Widgets" might convey the overall subject of a documentation resource, but fails to provide clear context as to what a ready can accomplish by reading it.

A more goal-oriented and user-centric title might be something like "Implement Doodads with Chainguard Widgets." This example starts with an action verb ("implement") and by taking the imperative voice, it lets the reader know what they will learn to do and with what.

General guidelines for titles on Academy:

• Shorter is usually better, though not at the expense of clarity.
• For titles starting with "How to…", the "to" should not be capitalized.
  • We've not been consistent about this in the past. If you're updating an existing document that capitalizes "to" in the title, be sure to change it.
• Titles using the following formats are acceptable for procedural tutorials:
  • "Verb X with Y"
  • "Verbing X with Y"
  • "How to Verb X with Y"
• Conceptual and Reference articles don't need to be imperative. For example, "Overview of Chainguard Images" is clear enough for readers to understand what the article covers.
  • That said, you can still use titles like "Understanding Widgets" for conceptual articles if you so choose.

LinkTitles

LinkTitles require a different approach than regular titles as they don't affect SEO and are, by their nature, shorter. Additionally, the format used for a linkTitle depends on the type of resource.

Conceptual articles or documents that outline how to use a specific feature can have linkTitles that consist of a noun with one or more optional descriptors. For example:

• Images Directory
• CVE Visualizations
• Product Release Lifecycle

If it makes sense, these kinds of resources can also use linkTitles that are formed as a question or start with "How", like these:

• What is an SBOM?
• How Images are Tested

Meanwhile, procedural tutorials should start with a verb:

• Using Chainguard Images
• Retrieve an Image's SBOM
• Compare Images with chainctl

General guidelines for linkTitles on Academy:

• LinkTitles should always follow the title case.
• Ideally, linkTitles should be short enough to stay on one line
• To keep a linkTitle's length to a minimum, avoid using gerunds and instead use the present tense of the active verb
  • This is not a strict rule. For example, a linkTitle like "Understanding Widgets" would not be improved by shortening it to "Understand Widgets."
• It can get repetitive for the same word or phrase to appear in numerous linkTitles. Even specifying "Chainguard" in multiple linkTitles in the same section can feel redundant.
• Use FAQ (not FAQs) as a standard linkTitle for FAQ pages.

Identifiers

Hugo assigns each menu entry an identifier to uniquely distinguish it within the docs menu. When no identifier is set explicitly, Hugo derives one from the page's linktitle (or title if linktitle is absent).

This causes a build warning whenever two pages share the same derived identifier:

WARN "path/to/file.md:1:1": duplicate menu entry with identifier "FAQ" in menu "docs"

When to set an identifier

Set identifier in menu.docs whenever a page's linktitle is a generic term that another page — now or in the future — might share. Common examples: FAQ, Overview, Build configuration, Global configuration.

The identifier must be unique across the entire docs menu, not just within a parent section.

Naming convention

Use title case and prefix with the product or section name to make the value self-documenting:

menu:
  docs:
    parent: "python"
    identifier: "Python Build Configuration"

Existing examples in the codebase: Chainguard Images FAQ, Java Global Configuration, Octo STS Overview.

Rule of thumb

If you're adding a page whose linktitle is a common noun or generic phrase, set identifier on that page and on any other pages under different parents that share the same linktitle. Setting it only on the duplicates that triggered the warning is fragile — Hugo's file processing order determines which entry "wins," and that order can change.