Skip to content

Make the site archetype a Markdown-only demonstration - #144

Closed
slachiewicz wants to merge 2 commits into
masterfrom
archetype-site-markdown-only
Closed

Make the site archetype a Markdown-only demonstration#144
slachiewicz wants to merge 2 commits into
masterfrom
archetype-site-markdown-only

Conversation

@slachiewicz

Copy link
Copy Markdown
Member

Makes maven-archetype-site a Markdown-only demonstration: a project generated from it no
longer starts life with four documentation formats to choose between.

This is a product decision about the archetype, not a mechanical conversion — a reviewer seeing
faq.fml deleted should know it is deliberate. The archetype should teach the format the project
recommends rather than preserve one sample per legacy format.

Stacked on #143 and branched from it, because it edits two pages that #143 converts. Merge
#143 first; this diff will then reduce to its own three commits. Merge or rebase, don't squash.

What changes

Converted, not deletedsrc/site/apt/index.apt and src/site/fr/apt/index.apt become
markdown/index.md and fr/markdown/index.md. They have to survive: it-basic/verify.groovy
asserts target/site/en/index.html and target/site/fr/index.html exist, and these generate them.

Deleted (6)apt/format.apt, fml/faq.fml, xdoc/xdoc.xml and the three fr/
equivalents.

Keptmarkdown/markdown.md, markdown/markdown-velocity.md.vm and both fr/ equivalents.

Both site descriptors lose the three menu entries whose pages are gone; leaving them would
generate a project whose menu 404s on first build. The remaining item names still say "Markdown",
which stays accurate and describes what the example demonstrates — I did not rename them.

Two pages that described the archetype are updated: this module's own index (its directory
tree listed every deleted file) and the aggregator's table.

The archetype descriptor needs no change — it ships src/site as a whole-directory
<fileSet> rather than listing files, so removals cannot break it. Checked specifically.

Verification

Ran the archetype IT (archetype:integration-test, goal clean site), which generates a project
and builds its site, on this branch and on pristine master:

  • IT passes, both index.html assertions included
  • generated pages: exactly fr/faq.html, fr/format.html and fr/xdoc.html disappear
  • every remaining page differs only by the three removed menu entries — verified page by page
  • the converted fr/index.html is otherwise byte-identical in visible text and metadata

A pre-existing bug this uncovered — worth its own issue, not fixed here

The generated project sets <locales>en,fr</locales>. The non-localized src/site/** content
is never rendered at all.
On current master, a freshly generated project produces:

  • en/index.html — the auto-generated About report, not the archetype's index page
  • fr/index.html — the archetype's real index page
  • the five sample pages only ever appear under fr/

so the English menu links to format.html, faq.html, markdown.html, markdown-velocity.html
and xdoc.html, and all five 404. That is today's behaviour, unchanged by this PR; this
change happens to reduce the broken English links from five to two, but does not fix the cause.

It also means the English markdown/index.md in this PR is not exercised by any build — the
French one is what the IT renders and what I verified. Flagging that rather than implying both
sides are covered.

Local runs are JDK 21 / Maven 3.9.16 / macOS only; CI is the real check.

Generated with assistance from Claude Opus 5.

@slachiewicz slachiewicz added the documentation Improvements or additions to documentation label Aug 10, 2026
@slachiewicz
slachiewicz marked this pull request as ready for review August 10, 2026 01:04
The site archetype is becoming a Markdown-only demonstration, and its two
index pages have to survive that as Markdown rather than be deleted: the
archetype's own integration test asserts that target/site/en/index.html
and target/site/fr/index.html exist, and those come from these files.

Move them first, unchanged, so the conversion shows up as an edit rather
than as a delete and an add.

Generated-by: Claude Opus 5 (1M context)
The archetype shipped one sample per Doxia format - APT, xdoc, FML and
Markdown, in both locales - so a project generated from it started life
with four documentation formats to choose between. Ship only the format
the project recommends.

Convert both index pages to Markdown rather than deleting them: the
archetype's own integration test asserts that target/site/en/index.html
and target/site/fr/index.html exist, and they are generated from these.
Delete the six remaining APT, xdoc and FML samples, and drop their three
entries from each site descriptor - leaving them would generate a project
whose menu 404s on first build. The menu item names still say "Markdown",
which stays accurate and says what the example demonstrates.

The archetype descriptor needs no change: it ships src/site as a whole
directory fileset rather than listing files, so removals cannot break it.

Update the two pages that describe the archetype's contents - this
module's own index and the aggregator's table - since both still listed
the formats that are going away.

Verified by running the archetype IT, which generates a project and builds
its site: it passes, and every generated page is unchanged apart from the
three menu entries that were removed.

Generated-by: Claude Opus 5 (1M context)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant