MorphiaOrg / MorphiaOrg/morphia

Migrate documentation from Antora to Hugo

Open
#4,246 0 comments 0 reactions 1 assignee View on GitHub

@evanchooly is already working on this.

Since May 6, 2026.

docs migration Task
Dominant language
Java
Stars
1.7k
Forks
449
Avg merge
7m
Merged PRs (30d)
10

Description

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/)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.