maven-site-plugin
maven-site-plugin copied to clipboard
apache
[MSITE-869] Options to preprocess site sources and resources through Maven filtering
Bertrand Martin opened MSITE-869 and commented
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 in src/site/resource/openapi.yaml
- the title of a Markdown document describing the project (like Maven Site Plugin's own documentation)
Workaround
Usually, it is recommended to add the .vm suffix 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 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.
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:
@Component(role = MavenResourcesFiltering.class, hint = "default")
private MavenResourcesFiltering mavenResourcesFiltering;
.vm files don't need to be filtered. There are therefore 3 cases:
- no filtering
- simple filtering (like Maven Resource Plugin)
- advanced templating
Issue Links:
- DOXIA-677 Macro for printing project properties ("duplicates")
Backported to: wontfix-candidate
Bertrand Martin commented
Yes, but I think MSITE-869 is better explained and specified than DOXIA-677 😁
Michael Osipov commented
The problem, yes, but not the solution. I believe this can already be solved with https://maven.apache.org/plugins/maven-site-plugin/site-mojo.html#generatedSiteDirectory. filter from {{src/site-filtered} to that target and you get what you want. No changes here necessary. If this works, I will close this issue.
Bertrand Martin commented
I'm sorry but I don't see how this could solve the problem entirely. Are you suggesting invoking the maven-resource-plugin in the pre-site or post-site phase?
Bertrand Martin commented
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)
Michael Osipov commented
I'll try to add a sample IT which will link from the documentation, that should be enough. If you can work on this, that's be great.
On adding resources:resources to the default lifecycle: I don't know whether everyone requires it, 5 to 10% would add this burden to the rest. Doesn't sound reasonable. As for src/site: I consider this wrong. It should be src/site-filtered, just like with src/resources-filtered but even if, there is no way in the POM to configure this filtering, if required. So I still think that is has to remain manual (for now).