Migrate documentation from Antora to Hugo

[Copilot]

Converts documentation build system from Antora to Hugo. All AsciiDoc pages migrated to Markdown with Hugo-compatible syntax.

Infrastructure

• Layouts: Custom templates (base, single, list, header, footer, sidebar) - no theme dependency
• Shortcodes: Notice blocks for callouts (note, warning, tip, important)
• Styling: Self-contained CSS with responsive layout
• Navigation: Menu structure defined in data/menu.yaml

Content Migration

Converted 13 feature pages from .adoc to .md:

• Core features: mapping, queries, updates, deletes, aggregations
• Advanced: indexing, transactions, references, lifecycle-methods, schema-validation
• Language: kotlin, text-search, sharding

Key conversions:

• AsciiDoc headings (==, ===) → Markdown (##, ###)
• Code blocks ([source,java] ----) → fenced blocks (```java)
• Cross-references (xref:page.adoc) → relative paths (/features/page/)
• Admonitions ([NOTE], [WARNING]) → shortcodes ({{% notice type %}})
• Javadoc links normalized to /javadoc/ prefix

Build System

make build  # Production build with minification
make serve  # Local dev server with live reload
make clean  # Remove generated files

Before: Required Antora toolchain and Ruby dependencies
After: Single Hugo binary, generates 28 pages in ~40ms

Cleanup

• Removed antora.yml
• Updated pom.xml to remove Antora-specific Maven plugin configuration
• Added .gitignore for Hugo artifacts (public/, resources/_gen/)

Screenshots

Home page with navigation:

Feature page with converted content:

Original prompt

Overview

Convert the Antora-based documentation in docs/ folder to use Hugo instead. The branch docs-hugo already has some initial files created:

• docs/hugo.toml - Hugo configuration
• docs/content/_index.md - Main index
• docs/content/getting-started/_index.md - Getting started section
• docs/content/getting-started/quicktour.md
• docs/content/getting-started/migrating.md
• docs/content/features/_index.md
• docs/content/features/configuration.md

Remaining Tasks

1. Complete the Hugo infrastructure files

Create the following infrastructure files:

docs/archetypes/default.md - Default archetype for new content:

---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true
---

docs/layouts/_default/baseof.html - Base template
docs/layouts/_default/single.html - Single page template
docs/layouts/_default/list.html - List page template
docs/layouts/partials/header.html - Header partial
docs/layouts/partials/footer.html - Footer partial
docs/layouts/partials/sidebar.html - Sidebar navigation partial
docs/layouts/shortcodes/notice.html - Notice shortcode for notes/warnings

docs/static/css/style.css - Basic styling for the documentation site

docs/data/menu.yaml - Navigation menu structure matching the current Antora nav.adoc

2. Convert remaining Antora .adoc pages to Hugo Markdown

Convert these pages from docs/modules/ROOT/pages/ to docs/content/features/:

• mapping.md - from mapping.adoc
• queries.md - from queries.adoc
• updates.md - from updates.adoc
• deletes.md - from deletes.adoc
• aggregations.md - from aggregations.adoc
• indexing.md - from indexing.adoc
• transactions.md - from transactions.adoc
• references.md - from references.adoc
• lifecycle-methods.md - from lifeCycleMethods.adoc
• schema-validation.md - from schemaValidation.adoc
• kotlin.md - from kotlin.adoc
• text-search.md - from textSearches.adoc
• sharding.md - from sharding.adoc

3. Create support section

docs/content/support/_index.md - Support and issues page

4. Add build files

docs/Makefile - For building the Hugo site:

.PHONY: build serve clean

build:
	hugo --minify

serve:
	hugo server -D

clean:
	rm -rf public/

docs/.gitignore - Ignore Hugo build artifacts:

public/
resources/_gen/
.hugo_build.lock

5. Update/remove old Antora files

• Remove docs/antora.yml (no longer needed)
• Update docs/pom.xml to remove Antora-specific configuration or remove it entirely if not needed

6. Add README

docs/README.md - Documentation for building and contributing to the docs:

# Morphia Documentation

This folder contains the Hugo-based documentation for Morphia.

## Building

```bash
# Install Hugo (https://gohugo.io/installation/)
# Then run:
make serve  # For local development
make build  # For production build

Structure

• content/ - Markdown documentation files
• layouts/ - HTML templates
• static/ - Static assets (CSS, images, etc.)
• data/ - Data files for menus and configuration

## Reference
- Consult `MorphiaOrg/morphia-docs` repository for the base site structure patterns
- The existing `docs/modules/ROOT/nav.adoc` shows the navigation structure to replicate
- Keep the same documentation content, just convert from AsciiDoc to Markdown format

This pull request was created from Copilot chat.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.