Skip to content

Migrate documentation from Antora to Hugo #4246

@evanchooly

Description

@evanchooly

Overview

Migrate the Morphia documentation build system from Antora to Hugo, converting all AsciiDoc content to Markdown.

Infrastructure

  • Custom layouts (base, single, list, header, footer, sidebar) — no theme dependency
  • Shortcodes for notice/callout blocks (note, warning, tip, important)
  • Self-contained CSS with responsive layout
  • Navigation menu defined in data/menu.yaml
  • Makefile for build, serve, and clean targets

Content Migration

Convert all pages from docs/modules/ROOT/pages/ (.adoc) to docs/content/ (.md):

  • Getting started: quicktour, migrating, configuration
  • Features: mapping, queries, updates, deletes, aggregations, indexing, transactions, references, lifecycle-methods, schema-validation, kotlin, text-search, sharding
  • Support section

Conversion rules

AsciiDoc Markdown/Hugo
==, === headings ##, ###
[source,java] ---- code blocks Fenced ```java blocks
xref:page.adoc cross-references Relative paths (/features/page/)
[NOTE], [WARNING] admonitions {{% notice type %}} shortcodes
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: Antora toolchain with Ruby dependencies
After: Single Hugo binary

Cleanup

  • Remove docs/antora.yml
  • Update docs/pom.xml to remove Antora-specific Maven plugin configuration
  • Add .gitignore for Hugo artifacts (public/, resources/_gen/)

Metadata

Metadata

Assignees

Labels

TaskdocsmigrationIssue contains updates that should be noted in a migration document

Type

No fields configured for Task.

Projects

No projects

Relationships

None yet

Development

No branches or pull requests

Issue actions