Quick Start

Create the basic Antora structure:

docs/
├── antora.yml
├── modules/
│   └── ROOT/
│       ├── nav.adoc
│       ├── pages/
│       │   ├── index.adoc
│       │   ├── policies/
│       │   └── procedures/
│       └── partials/
│           └── attributes.adoc

Sample antora.yml:

YAML
name: policy-system
title: Policy & Manual Management
version: '1.0'
start_page: ROOT:index.adoc
nav:
- modules/ROOT/nav.adoc

Workflow

• Identify policy categories (HR, IT, Finance, etc.)
• Map policy hierarchy (policies → procedures → guidelines)
• Define approval workflows and version control needs
• Plan cross-references and dependencies

• Create module structure per policy domain
• Set up navigation hierarchy in nav.adoc
• Define consistent attributes in partials/attributes.adoc
• Establish naming conventions for policy documents

• Create AsciiDoc templates for different policy types
• Include metadata sections (effective date, review cycle, owner)
• Add approval tracking and revision history
• Set up cross-reference patterns

• Configure Antora playbook for multi-version support
• Set up automated builds from policy repository
• Configure output formats (HTML, PDF if needed)
• Test navigation and cross-references

Examples

Example 1: Policy Document Structure

ASCIIDOC
= Data Protection Policy
:policy-id: IT-001
:effective-date: 2024-01-01
:review-cycle: Annual
:policy-owner: IT Security Team
:version: 2.1

== Purpose

This policy establishes requirements for...

== Scope

This policy applies to:
* All employees and contractors
* All data processing activities
* Cloud and on-premises systems

== Policy Statement

[.policy-requirement]
****
All personal data MUST be encrypted at rest using AES-256 or equivalent.
****

== Procedures

Refer to xref:procedures/data-encryption.adoc[Data Encryption Procedures].

== Compliance

Non-compliance may result in disciplinary action up to and including termination.

== Related Documents

* xref:policies/information-security.adoc[Information Security Policy]
* xref:procedures/incident-response.adoc[Incident Response Procedures]

Example 2: Navigation Structure

ASCIIDOC
* xref:index.adoc[Policy Management System]
* Policies
** xref:policies/information-security.adoc[Information Security]
** xref:policies/data-protection.adoc[Data Protection]
** xref:policies/acceptable-use.adoc[Acceptable Use]
* Procedures
** xref:procedures/access-control.adoc[Access Control]
** xref:procedures/data-encryption.adoc[Data Encryption]
* Guidelines
** xref:guidelines/password-creation.adoc[Password Creation]

Best Practices

Content Organization:

• Use consistent document IDs (HR-001, IT-002, FIN-003)
• Separate policies (what) from procedures (how) from guidelines (recommendations)
• Create a master index with policy status and review dates

AsciiDoc Conventions:

• Use attributes for policy metadata at document top
• Apply consistent styling with custom CSS classes
• Use admonition blocks for critical requirements
• Implement consistent cross-referencing patterns

Version Control:

• Tag policy versions in git for audit trail
• Use Antora's version management for historical access
• Include effective dates and superseded document tracking
• Maintain change logs for significant policy updates

Approval Workflows:

• Create review templates with approval checkboxes
• Use git branch protection for policy changes
• Implement required reviewers for different policy types
• Generate approval reports from git history

Common Pitfalls

Structure Issues:

• Don't mix policy content with implementation details
• Avoid deep nesting (max 3 levels in navigation)
• Don't duplicate content across policies—use includes and cross-references

Maintenance Problems:

• Don't set unrealistic review cycles (quarterly for everything)
• Avoid orphaned procedures without parent policies
• Don't ignore broken cross-references in builds

Compliance Gaps:

• Don't forget to version-control approval records
• Avoid unclear policy ownership assignments
• Don't publish policies without proper review workflow

Technical Mistakes:

• Don't hardcode dates—use attributes
• Avoid inconsistent document ID schemes
• Don't skip testing multi-version navigation
• Avoid complex conditional content that breaks in different output formats