Phase 03: Content Patterns

Phase 3: Content Patterns

Antora organizes content into four resource types. Understanding when to use each is critical.

Pages vs Partials vs Examples vs Images

Type Location When to Use

Type	Location	When to Use
Pages	`modules/ROOT/pages/`	Standalone documents with their own URL. Every page is navigable.
Partials	`modules/ROOT/partials/`	Reusable fragments included in pages. No URL of their own. Use for: tables that appear in multiple pages, standard procedures, boilerplate sections.
Examples	`modules/ROOT/examples/`	Code blocks, scripts, config files >10 lines. Included in pages with syntax highlighting.
Images	`modules/ROOT/images/`	Diagrams, screenshots, logos. Referenced with `image::filename.png[]`.

Pages

modules/ROOT/pages/

Standalone documents with their own URL. Every page is navigable.

Partials

modules/ROOT/partials/

Reusable fragments included in pages. No URL of their own. Use for: tables that appear in multiple pages, standard procedures, boilerplate sections.

Examples

modules/ROOT/examples/

Code blocks, scripts, config files >10 lines. Included in pages with syntax highlighting.

Images

modules/ROOT/images/

Diagrams, screenshots, logos. Referenced with image::filename.png[].

Including Partials

A partial is content that appears in more than one place, or that you want to manage separately from the page.

Create the partial:

partials/common/change-control-note.adoc

[IMPORTANT]
====
All changes require a CR (Change Request) with pre/post verification.
Follow the change control process before modifying production systems.
====

Include it in any page:

include::partial$common/change-control-note.adoc[]

Including Examples (Code Blocks)

For scripts and config files longer than 10 lines, store them as examples.

Create the example:

examples/scripts/backup-switch.sh

#!/bin/bash
# Backup running config from Cisco switch
HOST=$1
USER=${2:-admin}
ssh $USER@$HOST "show running-config" > "backup-$(date +%Y%m%d)-$HOST.txt"
echo "Backup saved for $HOST"

Include it in a page:

[source,bash]
....
include::example$scripts/backup-switch.sh[]
....

Cross-References

Same component:

See xref:runbooks/switch-upgrade.adoc[Switch Upgrade Procedure].

Different component (double colon):

See xref:nac-ops::policies/dot1x.adoc[802.1X Policy] in the NAC operations guide.

Code Blocks with Attributes

When a code block contains attribute references, add subs=attributes+:

[source,bash,subs=attributes+]
----
ssh admin@{sw-core-01-ip}
show vlan brief | include {vlan-data}
----

This renders the attribute values instead of the literal {sw-core-01-ip} text.

Document Header Template

Every page should start with:

= Page Title
:description: Brief description of this page
:icons: font

No :toc: — Antora provides a sidebar TOC globally. Adding :toc: creates a duplicate.

Admonitions

NOTE: Informational context.

TIP: Helpful suggestion.

IMPORTANT: Must be followed.

WARNING: Risk of failure if ignored.

CAUTION: Potential for harm.