Make the site archetype a Markdown-only demonstration - #144
Closed
slachiewicz wants to merge 2 commits into
Closed
Conversation
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)
slachiewicz
force-pushed
the
archetype-site-markdown-only
branch
from
August 10, 2026 01:05
ecb8a61 to
8fd901a
Compare
This was referenced Aug 10, 2026
Open
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Makes
maven-archetype-sitea Markdown-only demonstration: a project generated from it nolonger 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.fmldeleted should know it is deliberate. The archetype should teach the format the projectrecommends rather than preserve one sample per legacy format.
What changes
Converted, not deleted —
src/site/apt/index.aptandsrc/site/fr/apt/index.aptbecomemarkdown/index.mdandfr/markdown/index.md. They have to survive:it-basic/verify.groovyasserts
target/site/en/index.htmlandtarget/site/fr/index.htmlexist, and these generate them.Deleted (6) —
apt/format.apt,fml/faq.fml,xdoc/xdoc.xmland the threefr/equivalents.
Kept —
markdown/markdown.md,markdown/markdown-velocity.md.vmand bothfr/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/siteas a whole-directory<fileSet>rather than listing files, so removals cannot break it. Checked specifically.Verification
Ran the archetype IT (
archetype:integration-test, goalclean site), which generates a projectand builds its site, on this branch and on pristine
master:index.htmlassertions includedfr/faq.html,fr/format.htmlandfr/xdoc.htmldisappearfr/index.htmlis otherwise byte-identical in visible text and metadataA pre-existing bug this uncovered — worth its own issue, not fixed here
The generated project sets
<locales>en,fr</locales>. The non-localizedsrc/site/**contentis 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 pagefr/index.html— the archetype's real index pagefr/so the English menu links to
format.html,faq.html,markdown.html,markdown-velocity.htmland
xdoc.html, and all five 404. That is today's behaviour, unchanged by this PR; thischange happens to reduce the broken English links from five to two, but does not fix the cause.
It also means the English
markdown/index.mdin this PR is not exercised by any build — theFrench 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.