elharo commented on code in PR #1809: URL: https://github.com/apache/maven-site/pull/1809#discussion_r4468537090
########## content/markdown/guides/mini/guide-site.md: ########## @@ -324,6 +324,45 @@ With either setup, note the following: - Resource filtering also replaces `@...@` expressions by default. If a page contains such text, for example an email address, set `<useDefaultDelimiters>false</useDefaultDelimiters>` and declare only the delimiters you need. - Keep binary files, such as images, out of the filtered directory, or copy them with a second `<resource>` without filtering, because filtering can corrupt them. +## 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. + +The parameter lists `configuration` elements below the id of the parser (`markdown`, `xdoc`, `apt` and so on). Each element sets properties of the parser, for example `emitComments` or `emitAnchorsForIndexableEntries`, and optionally restricts them to `patterns`: + +```xml +<plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-site-plugin</artifactId> + <configuration> + <parserConfigurations> + <markdown> + <configuration> + <patterns> + <pattern>glob:**/markdown/drafts/*.md</pattern> + </patterns> + <emitComments>true</emitComments> + </configuration> + </markdown> + <xdoc> + <configuration> + <emitComments>true</emitComments> + </configuration> + </xdoc> + </parserConfigurations> + </configuration> +</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. Review 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 ########## content/markdown/guides/mini/guide-site.md: ########## @@ -324,6 +324,45 @@ With either setup, note the following: - Resource filtering also replaces `@...@` expressions by default. If a page contains such text, for example an email address, set `<useDefaultDelimiters>false</useDefaultDelimiters>` and declare only the delimiters you need. - Keep binary files, such as images, out of the filtered directory, or copy them with a second `<resource>` without filtering, because filtering can corrupt them. +## 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. Review Comment: I had to read the sentence "The Maven Site Plugin renders every source file with the [Doxia](/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](/doxia/) parser for the source file's format (markdown, xdoc, apt and so on). ########## content/markdown/guides/mini/guide-site.md: ########## @@ -324,6 +324,45 @@ With either setup, note the following: - Resource filtering also replaces `@...@` expressions by default. If a page contains such text, for example an email address, set `<useDefaultDelimiters>false</useDefaultDelimiters>` and declare only the delimiters you need. - Keep binary files, such as images, out of the filtered directory, or copy them with a second `<resource>` without filtering, because filtering can corrupt them. +## 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. + +The parameter lists `configuration` elements below the id of the parser (`markdown`, `xdoc`, `apt` and so on). Each element sets properties of the parser, for example `emitComments` or `emitAnchorsForIndexableEntries`, and optionally restricts them to `patterns`: + +```xml +<plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-site-plugin</artifactId> + <configuration> + <parserConfigurations> + <markdown> + <configuration> + <patterns> + <pattern>glob:**/markdown/drafts/*.md</pattern> + </patterns> + <emitComments>true</emitComments> + </configuration> + </markdown> + <xdoc> + <configuration> + <emitComments>true</emitComments> + </configuration> + </xdoc> + </parserConfigurations> + </configuration> +</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. Review Comment: below --> inside -- 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]
