[
https://issues.apache.org/jira/browse/MSITE-869?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17683502#comment-17683502
]
Bertrand Martin commented on MSITE-869:
---------------------------------------
Okay then, I guess that works!
A sample {{pom.xml}} could be provided as an example, to explain to users how
to achieve that easily. I would even advise to add {{resources:resources}} to
the default lifecycle for {{site}} (although it requires a specific
configuration to filter files from {{src/site}} to {{target/generated-site}})
> Options to preprocess site sources and resources through Maven filtering
> ------------------------------------------------------------------------
>
> Key: MSITE-869
> URL: https://issues.apache.org/jira/browse/MSITE-869
> Project: Maven Site Plugin
> Issue Type: Improvement
> Components: property interpolation
> Reporter: Bertrand Martin
> Priority: Major
> Fix For: waiting-for-feedback, wontfix-candidate
>
>
> h1. Use Case
> User has source files or resources files where Maven properties like
> ${project.version} or ${project.name} need to be replaced with their actual
> value.
> Examples:
> * a [REST API specification|https://swagger.io/specification/] in
> *src/site/resource/openapi.yaml*
> * the title of a Markdown document describing the project (like [Maven Site
> Plugin|https://maven.apache.org/plugins/maven-site-plugin/index.html]'s own
> documentation)
> h1. Workaround
> Usually, [it is recommended to add the .vm
> suffix|https://stackoverflow.com/questions/7111000/resource-filtering-with-maven-site-plugin]
> to the files that need filtering, so that they are processed as a Velocity
> template.
> But this workaround has several drawbacks:
> * [Velocity and Markdown formats are highly
> incompatible|https://github.com/apache/maven-archetypes/blob/master/maven-archetype-plugin-site/src/main/resources/archetype-resources/src/site/markdown/markdown-velocity.md.vm]
> because of the headings format
> * Velocity has 1000 times more features than just filtering, which is great,
> but also which can unexpectedly conflict with source files and with resource
> files (which may be from external sources, like JS libraries, YAML, etc.)
> * .vm files are handled as Velocity templates in most code editors (VSCode,
> etc.), which prevents any other advanced features from working (especially on
> openapi.yaml, where you can have linting, validation, autosuggest, etc.)
> Basically, Velocity templates is a great feature that needs to stay, but it's
> overkill for just replacing ${project.version} in a bunch of files.
> h1. Specifications
> Add options to filter site source files and resource files:
> * {{boolean sourceFiltering}} (default: false)
> * {{boolean resourceFiltering}} (default: false)
> * {{List<String> nonFilteredFileExtensions}} (default: jpg, jpeg, gif, bmp,
> png)
> * {{boolean fileNameFiltering}} (default: false)
> Use Maven's filtering component:
> {code:java}
> @Component(role = MavenResourcesFiltering.class, hint = "default")
> private MavenResourcesFiltering mavenResourcesFiltering;
> {code}
> .vm files don't need to be filtered. There are therefore 3 cases:
> * no filtering
> * simple filtering (like [Maven Resource
> Plugin|https://maven.apache.org/plugins/maven-resources-plugin/examples/filter.html])
> * advanced templating
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
