From 758038a4c068c512c788c7f6a6324b338ed19133 Mon Sep 17 00:00:00 2001 From: Sylwester Lachiewicz Date: Mon, 10 Aug 2026 02:00:32 +0200 Subject: [PATCH 1/2] Rename the FAQ ahead of converting it Git records a rename plus a rewrite in one commit as a delete and an add, which stops 'git log --follow'. Splitting the rename out keeps the history. Please merge or rebase rather than squash. Generated-by: Claude Opus 5 (1M context) --- maven-archetype-plugin/src/site/{fml/faq.fml => markdown/faq.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename maven-archetype-plugin/src/site/{fml/faq.fml => markdown/faq.md} (100%) diff --git a/maven-archetype-plugin/src/site/fml/faq.fml b/maven-archetype-plugin/src/site/markdown/faq.md similarity index 100% rename from maven-archetype-plugin/src/site/fml/faq.fml rename to maven-archetype-plugin/src/site/markdown/faq.md From cfae102a9663bcbc573d8a7887fa023bd9292a94 Mon Sep 17 00:00:00 2001 From: Sylwester Lachiewicz Date: Mon, 10 Aug 2026 02:04:43 +0200 Subject: [PATCH 2/2] Convert the FAQ from FML to Markdown doxia-converter cannot target FML usefully - the questions come out as link-reference syntax rather than headings, the [top] back-links become links to a nonexistent 'top' page, and the contents links lose their # anchors. The page is written out by hand instead. Explicit anchors keep the existing deep links working. Markdown derives a heading anchor from the question text, which is not the the site serves, so each id is written out as an ahead of its heading. Verified by building the site before and after and comparing the set of anchors the generated faq.html actually serves. Every anchor present before is still present after: before: packaging, authentication, old, excludes, top, bodyColumn after: the same six, plus five heading-derived ids The is byte-identical, so the title and metadata are unchanged. site.xml needs no edit - src/site/fml/faq.fml and src/site/markdown/faq.md both render to faq.html. FML generates a [top] back-link after each answer; those are dropped rather than hand-written. The question now renders as an h3 heading instead of a definition term. Those are the only rendering losses. Generated-by: Claude Opus 5 (1M context) --- .../src/site/markdown/faq.md | 116 ++++++++++-------- 1 file changed, 63 insertions(+), 53 deletions(-) diff --git a/maven-archetype-plugin/src/site/markdown/faq.md b/maven-archetype-plugin/src/site/markdown/faq.md index e51846ea..89877061 100644 --- a/maven-archetype-plugin/src/site/markdown/faq.md +++ b/maven-archetype-plugin/src/site/markdown/faq.md @@ -1,4 +1,6 @@ - +--- +title: Frequently Asked Questions +--- - - - - - - What packaging should I use: maven-archetype or jar? What is the difference? - -

maven-archetype packaging is available since 2.0-alpha-1: it should be used instead of jar, which was used - for Old Archetype 1.0.x.

-

Using maven-archetype packaging helps identifying archetypes in repositories and adds archetype related bindings to - build lifecycle: see maven-archetype packaging documentation - for more information.

- - - - - How to generate a project from an archetype in a custom (potentially authenticated) repository? - -

The server/repository id used to download the catalog is archetype: You have to - define corresponding server configuration and repository in - settings.xml with this id to generate a project based on the catalog - In case of mirroring the mirror id of that mirror which - matches repository id archetype or central is used for authentication. - For resolving the actual archetype an artificial repository with id <archetype-artifactId>-repo is used in case - the underlying Archetype Catalog Item contained a repository (leveraging its URL). - As fallback all regular remote repositories (as defined in the settings.xml) are tried.

- - - - - What is "Old Archetype 1.0.x"? - -

Old Archetype 1.0.x was using a archetype XML descriptor defined in /xsd/archetype-1.0.0.xsd: - see old descriptor reference.

-

Archetype is now using archetype-descriptor XML descriptor defined in /xsd/archetype-descriptor-1.1.0.xsd: - see Archetype descriptor reference.

-

For compatibility, old archetypes can still be used to generate new projects, but archetypes should be updated to the new - descriptor format: in the future, old format will be removed.

- - - - - How do I get files like .gitignore included into my archetype? - -

First make sure you set addDefaultExcludes to false in the maven-resources-plugin - so that the archetype-plugin gets to see these files.

-

Then set useDefaultExcludes to false in the maven-archetype-plugin.

- - - - - + + +# Frequently Asked Questions + +1. [What packaging should I use: `maven-archetype` or `jar`? What is the difference?](#packaging) +1. [How to generate a project from an archetype in a custom (potentially authenticated) repository?](#authentication) +1. [What is "Old Archetype 1.0.x"?](#old) +1. [How do I get files like `.gitignore` included into my archetype?](#excludes) + + + +### What packaging should I use: `maven-archetype` or `jar`? What is the difference? + +`maven-archetype` packaging is available since 2.0-alpha-1: it should be used instead +of `jar`, which was used for Old Archetype 1.0.x. + +Using `maven-archetype` packaging helps identifying archetypes in repositories and +adds archetype related bindings to build lifecycle: see +[`maven-archetype` packaging documentation](../archetype-packaging/) for more +information. + + + +### How to generate a project from an archetype in a custom (potentially authenticated) repository? + +The server/repository id used to download the **catalog** is `archetype`: You have to +[define corresponding server configuration and repository in `settings.xml`](/settings.html#Servers) +with this id to generate a project based on the catalog In case of +[mirroring](/guides/mini/guide-mirror-settings.html) the mirror id of that mirror +which matches repository id `archetype` or `central` is used for authentication. +For resolving the **actual archetype** an artificial repository with id +`-repo` is used in case the underlying +[Archetype Catalog Item](/archetype/archetype-models/archetype-catalog/archetype-catalog.html) +contained a repository (leveraging its URL). As fallback all regular remote +repositories (as defined in the `settings.xml`) are tried. + + + +### What is "Old Archetype 1.0.x"? + +Old Archetype 1.0.x was using a `archetype` XML descriptor defined in +`/xsd/archetype-1.0.0.xsd`: see +[old descriptor reference](/archetype/archetype-common/archetype.html). + +Archetype is now using `archetype-descriptor` XML descriptor defined in +`/xsd/archetype-descriptor-1.1.0.xsd`: see +[Archetype descriptor reference](/archetype/archetype-models/archetype-descriptor/archetype-descriptor.html). + +For compatibility, old archetypes can still be used to generate new projects, but +archetypes should be updated to the new descriptor format: in the future, old format +will be removed. + + + +### How do I get files like `.gitignore` included into my archetype? + +First make sure you set `addDefaultExcludes` to `false` in the +`maven-resources-plugin` so that the archetype-plugin gets to see these files. + +Then set `useDefaultExcludes` to `false` in the `maven-archetype-plugin`.