slachiewicz opened a new pull request, #146:
URL: https://github.com/apache/maven-archetypes/pull/146
Extends the Markdown-only treatment to the two sibling demo archetypes. Both
handed a generated
project an APT `src/site` while shipping `markdown.md` and
`markdown-velocity.md.vm` beside it,
so a new project started life with two documentation formats and no reason
to prefer either.
Independent of #144 — different files, no overlap.
### Per-file judgement, as asked
| file | call | why |
|---|---|---|
| `plugin-site/…/apt/index.apt` | **convert** | the sample plugin's front
page — real content |
| `plugin-site/…/apt/usage.apt` | **convert** | a usage page the user fills
in — real content |
| `plugin-site/…/apt/examples/example.apt` | **convert** | a worked
SMTP-authentication example — real content |
| `site-simple/…/apt/index.apt` | **convert** | the generated project's
landing page — real content |
| — | **delete: none** | none of the four is a format demonstration |
That is the difference from `maven-archetype-site` in #144, where
`format.apt` existed *only* to
show what APT looks like and has no Markdown equivalent worth writing. Here
every page carries
content that survives translation, so nothing is deleted.
### Neither site descriptor needs a change — checked, not assumed
Conversion does not rename a generated page: `index.apt`→`index.md` still
produces `index.html`.
Every `href` in both menus resolves exactly as before, and no page is
removed, so there is nothing
to prune. Both menus are left alone.
For the record, entries like `faq.html`, `plugin-info.html`,
`changes-report.html` and
`jira-report.html` point at pages the template does not contain — they are
placeholders for the
user to enable, not breakage, and predate this change.
### The reference fixture moves in lockstep
`site-simple/src/test/resources/projects/it-basic/reference/` is the
expected *generated output*.
Its `src/site/apt/index.apt` is now `src/site/markdown/index.md`,
byte-identical to what the
archetype produces. The IT compares the two, so this is a real regression
test rather than a
copy that has to be kept in step by hand.
### Verification
Both archetypes' ITs (`archetype:integration-test`, goal `clean site`) run
before and after —
they generate a project and build its site:
* **both pass**, including site-simple's reference comparison
* the same pages are produced on both sides
* every generated page is identical in visible text,
`<title>`/`author`/`date` metadata,
structural tag sequence, and anchor id set
The only diff anywhere is the absolute build path inside
`distribution-management.html`, which
differs because the two runs were in different directories.
### Two things established by measurement, worth recording
**Archetype filtering does not eat ATX headings.** Both descriptors ship
`src/site` as a
`<fileSet>` without `filtered="false"`, so I checked whether `##` would be
swallowed as a Velocity
line comment at *generate* time. It is not: `### Subsection` in the existing
`markdown.md`
survives generation and renders as `<h3>`, and `${artifactId}` in the
generated `site.xml` is not
substituted either — `src/site` is effectively unfiltered. So these pages
keep ordinary ATX
headings; no setext workaround is needed for `.md` template content.
**Metadata is taken from each page's own APT header**, not harmonised across
siblings — the four
pages declare different authors and dates and keep them.
`site-simple/index.md` keeps its
placeholder `Title Here` / `Author Here` / `Date Here (AAAA-MM-DD)`, which
is what the template
is for.
Local runs are JDK 21 / Maven 3.9.16 / macOS only; CI is the real check.
Generated with assistance from Claude Opus 5.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
