Clarify where to configure the plugin (#558)

* Improve introduction to configuration, specially for people new to maven.
asciidoctor · Dec 9, 2021 · 7a0c6f8 · 7a0c6f8
1 parent 689ba56
commit 7a0c6f8
Show file tree

Hide file tree

Showing 2 changed files with 30 additions and 23 deletions.
diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc
@@ -16,6 +16,7 @@ For a detailed view of what has changed, refer to the {uri-repo}/commits/main[co
 Documentation::
 
   * Add ID's for all parameters of process-asciidoc, auto-refresh and http mojo, to be able to generate direct urls (https://github.com/uniqueck[@uniqueck]) (#533)
+  * Clarify where to put the plugin section in `pom.xml` (#558)
 
 Bug Fixes::
 

diff --git a/docs/modules/plugin/pages/introduction.adoc b/docs/modules/plugin/pages/introduction.adoc
@@ -27,29 +27,35 @@ Here is a simple example of an HTML conversion.
 
 [source,xml,subs="attributes+"]
 ----
-<plugin>
-    <groupId>org.asciidoctor</groupId>
-    <artifactId>asciidoctor-maven-plugin</artifactId>
-    <version>{release-version}</version>
-    <executions>
-        <execution>
-            <id>convert-to-html</id>
-            <phase>generate-resources</phase> <!--.-->
-            <goals>
-                <goal>process-asciidoc</goal>
-            </goals>
-            <configuration>
-                <outputDirectory>${project.build.directory}/html</outputDirectory> <!--.-->
-                <attributes> <!--.-->
-                    <source-highlighter>coderay</source-highlighter>
-                    <imagesdir>./images</imagesdir>
-                    <toc>left</toc>
-                    <icons>font</icons>
-                </attributes>
-            </configuration>
-        </execution>
-    </executions>
-</plugin>
+<project>
+    ...
+    <build>
+        ...
+        <plugin>
+            <groupId>org.asciidoctor</groupId>
+            <artifactId>asciidoctor-maven-plugin</artifactId>
+            <version>{release-version}</version>
+            <executions>
+                <execution>
+                    <id>convert-to-html</id>
+                    <phase>generate-resources</phase> <!--.-->
+                    <goals>
+                        <goal>process-asciidoc</goal>
+                    </goals>
+                    <configuration>
+                        <outputDirectory>${project.build.directory}/html</outputDirectory> <!--.-->
+                        <attributes> <!--.-->
+                            <source-highlighter>coderay</source-highlighter>
+                            <imagesdir>./images</imagesdir>
+                            <toc>left</toc>
+                            <icons>font</icons>
+                        </attributes>
+                    </configuration>
+                </execution>
+            </executions>
+        </plugin>
+  ...
+</project>
 ----
 <.> Asciidoctor maven plugin's phase and goal must be set explicitly in an execution block.
 <.> Asciidoctor options can be set in the `<configuration>` section.