New domus-* Repository Checklist

Checklist for creating a new domus-* Antora documentation repository with full ecosystem integration.

Prerequisites

  • GitHub account with repo creation rights

  • GitLab account (EvanusModestus)

  • Gitea instance running (gitea-01.inside.domusdigitalis.dev)

  • SSH keys loaded for all three remotes

  • Cloudflare Pages access (if deploying standalone)

Repository Creation

1. Create Directory Structure

REPO_NAME="domus-<name>-ops"
mkdir -p ~/atelier/_bibliotheca/$REPO_NAME
cd ~/atelier/_bibliotheca/$REPO_NAME

# Standard Antora structure
mkdir -p docs/asciidoc/modules/ROOT/{pages,partials,images,examples}

2. Create antora.yml

cat > docs/asciidoc/antora.yml << 'EOF'
name: <component-name>
title: <Component Title>
version: ~
nav:
  - modules/ROOT/nav.adoc

asciidoc:
  attributes:
    # Add component-specific attributes here
EOF

3. Create antora-playbook.yml

cat > antora-playbook.yml << 'EOF'
site:
  title: <Site Title>
  url: https://<subdomain>.domusdigitalis.dev
  start_page: <component-name>::index.adoc

content:
  sources:
    - url: .
      branches: HEAD
      start_path: docs/asciidoc

ui:
  bundle:
    url: https://github.com/EvanusModestus/domus-antora-ui/releases/latest/download/ui-bundle.zip
    snapshot: true

antora:
  extensions:
    - '@antora/lunr-extension'

asciidoc:
  attributes:
    page-pagination: ''
    hide-uri-scheme: ''
    attribute-missing: skip
    kroki-server-url: http://localhost:18000
    kroki-fetch-diagram: true
  extensions:
    - '@asciidoctor/tabs'
    - asciidoctor-kroki

output:
  dir: ./build/site
  clean: true
EOF

4. Create Makefile

cat > Makefile << 'EOF'
.PHONY: build clean serve

PLAYBOOK := antora-playbook.yml
BUILD_DIR := build/site

build:
	@echo "Building site..."
	@npx antora $(PLAYBOOK)
	@echo "Site built: $(BUILD_DIR)/index.html"

clean:
	@rm -rf $(BUILD_DIR) .cache

serve: build
	@python3 -m http.server 8000 --directory $(BUILD_DIR)
EOF

5. Create Initial Pages

# Navigation
cat > docs/asciidoc/modules/ROOT/nav.adoc << 'EOF'
* xref:index.adoc[Home]
EOF

# Index page
cat > docs/asciidoc/modules/ROOT/pages/index.adoc << 'EOF'
= <Component Title>
:description: <Description>
:navtitle: Home

<Overview content here>
EOF

6. Create README.adoc

cat > README.adoc << 'EOF'
= <Repo Name>

<Description>

== Quick Start

[source,bash]

make build make serve

== Structure

.Antora Spoke Repository Structure
image::diagrams/antora-spoke-structure.svg[Antora Spoke Structure,width=100%]

== Integration

This component is part of the Domus Digitalis documentation ecosystem.
Built with https://antora.org[Antora].
EOF

Git Configuration

7. Initialize Git

git init
git branch -m main

8. Create GitHub Repository

gh repo create EvanusModestus/$REPO_NAME --public --source=. --remote=origin
git add -A
git commit -m "feat: Initial documentation structure"
git push -u origin main

9. Add GitLab Remote

# Create repo on GitLab first (manually or via API)
git remote add gitlab git@gitlab.com:EvanusModestus/$REPO_NAME.git
git push gitlab main

10. Add Gitea Remote

# Create repo on Gitea via tea CLI
tea repo create --name $REPO_NAME --private

# Add remote (uses SSH config alias)
git remote add gitea git@gitea:evanusmodestus/$REPO_NAME.git
git push gitea main

Shell Configuration

11. Update ~/.zshrc

Add to domus-push() function:

~/atelier/_bibliotheca/$REPO_NAME

Add aliases:

alias domus-<short>='cd ~/atelier/_bibliotheca/$REPO_NAME'
alias d<short>='cd ~/atelier/_bibliotheca/$REPO_NAME'

Aggregator Integration

12. Add to domus-docs (if aggregating)

Edit ~/atelier/_bibliotheca/domus-docs/antora-playbook.yml:

content:
  sources:
    # ... existing sources ...

    # New component
    - url: https://github.com/EvanusModestus/$REPO_NAME
      branches: main
      start_path: docs/asciidoc
      edit_url: false

Also update antora-playbook-local.yml:

    - url: /home/evanusmodestus/atelier/_bibliotheca/$REPO_NAME
      branches: HEAD
      start_path: docs/asciidoc

Cloudflare Pages (Standalone)

13. Add GitHub App Permissions

If deploying standalone via Cloudflare Pages:

  1. Go to Cloudflare Dashboard > Pages

  2. Settings > Builds & deployments > GitHub configuration

  3. Add repository access for new repo

Verification Checklist

  • Directory structure created

  • antora.yml at docs/asciidoc/antora.yml

  • antora-playbook.yml with GitHub UI bundle URL

  • Makefile with build/clean/serve targets

  • README.adoc

  • Git initialized with main branch

  • GitHub remote (origin)

  • GitLab remote

  • Gitea remote

  • Added to domus-push() in ~/.zshrc

  • Aliases added to ~/.zshrc

  • Added to domus-docs aggregator (if needed)

  • Cloudflare permissions (if standalone)

  • Test build: make build

  • Verify no xref errors

Common Issues

UI Bundle Not Found

Ensure using GitHub URL, not local path:

ui:
  bundle:
    url: https://github.com/EvanusModestus/domus-antora-ui/releases/latest/download/ui-bundle.zip

xref Errors

Use absolute paths from pages root, not relative:

// WRONG
xref:../other/page.adoc[]

// CORRECT
xref:category/subcategory/page.adoc[]

Branch Name

Always use main, not master:

git branch -m master main

See Also