Repository navigation
Document the configuration of Doxia parsers in the site guide - #1809
slachiewicz wants to merge 2 commits into
Conversation
|
|
||
| ## Configuring Parsers | ||
|
|
||
| The Maven Site Plugin renders every source file with the [Doxia](/doxia/) parser for its format. Since version 3.23.0 of the Maven Site Plugin, the [`parserConfigurations`](/plugins/maven-site-plugin/site-mojo.html#parserConfigurations) parameter sets properties of these parsers, for all files of a format or only for files at a given path. |
There was a problem hiding this comment.
I had to read the sentence "The Maven Site Plugin renders every source file with the Doxia parser for its format." before I realized what it was saying. I suggest something like
The Maven Site Plugin converts every source file to HTML using the Doxia parser for the source file's format (markdown, xdoc, apt and so on).
| </plugin> | ||
| ``` | ||
|
|
||
| In this example, comments in Markdown files below a `drafts` directory and in all XDoc files end up in the generated HTML. Other Markdown files keep the default of the Maven Site Plugin and drop their comments. |
| A pattern starts with `glob:` or `regex:` and is matched against the absolute path of the source file: | ||
|
|
||
| - A `glob:` pattern separates directories with `/` on every platform. | ||
| - A `regex:` pattern sees the platform's own separator, `\` on Windows. To work on every platform, accept both with an alternation, such as `regex:.*(/|\\)drafts(/|\\).*\.md`. Avoid a character class such as `[/\\]` followed by an escaped character: on macOS with Java 8 such a pattern fails to compile. |
There was a problem hiding this comment.
This feels wrong. There should be one syntax that works across platforms. Maybe an additional layer of indirection is needed here so the regex doesn't apply directly to platform dependent paths
There was a problem hiding this comment.
This is how it works now..
There was a problem hiding this comment.
so is the problem in doxia or somewhere else? where does this need to be improved?
Adds a "Configuring Parsers" section to the site guide for the
parserConfigurationsparameter that apache/maven-site-plugin#1346 (MSITE-1000) adds in Maven Site Plugin 3.23.0, which links here. Merge it once 3.23.0 is released.The
regex:advice comes from a CI failure on that PR: on macOS the regex path matcher compiles withPattern.CANON_EQ, and Java 8 rejects[/\\]followed by an escaped character under that flag.