Merge pull request #150 from ge0ffrey/jbake-maven-plugin-new-usage

jbake-maven-plugin is now part of the jbake release lifecycle
jbake-org · Jan 2, 2022 · 65faf84 · 65faf84
2 parents 36b5a67 + 33a49c8
commit 65faf84
Show file tree

Hide file tree

Showing 4 changed files with 116 additions and 9 deletions.
diff --git a/content/docs/latest/build-tool-integration.adoc b/content/docs/latest/build-tool-integration.adoc
@@ -6,23 +6,82 @@
 
 == Maven Plugin
 
-There is a http://maven.apache.org[Maven] plugin that allows you to run JBake from your Maven build.
-
-* https://github.com/jbake-org/jbake-maven-plugin[Plugin on GitHub]
-
-The plugin is available from the Maven Central repository using the following coordinates:
+The JBake Maven plugin allows you to run JBake from your http://maven.apache.org[Maven] build.
+It is available from the Maven Central repository using the following coordinates:
 
 [source,xml]
 ----
 <dependency>
     <groupId>org.jbake</groupId>
     <artifactId>jbake-maven-plugin</artifactId>
-    <version>0.3.2</version>
+    <version>${jbakeVersion}</version>
 </dependency>
 ----
 
 The plugin was originally created by https://github.com/aldrinleal[Aldrin Leal].
 
+=== Usage (maven plugin)
+
+To use JBake Maven Plugin, add the plugin in your `pom.xml`:
+
+----
+<build>
+    <plugins>
+        <plugin>
+            <groupId>org.jbake</groupId>
+            <artifactId>jbake-maven-plugin</artifactId>
+            <version>${jbakeVersion}</version>
+            <configuration>
+                <inputDirectory>${project.basedir}</inputDirectory>
+                <outputDirectory>${project.build.directory}/website</outputDirectory>
+            </configuration>
+            <executions>
+                <execution>
+                    <phase>generate-resources</phase>
+                    <goals>
+                        <goal>generate</goal>
+                    </goals>
+                </execution>
+            </executions>
+        </plugin>
+    </plugins>
+</build>
+----
+
+This configuration expects this directory structure:
+
+----
+my-project/
+    assets/
+        my-logo.png
+        ...
+    content/
+        my-page.adoc
+        ...
+    templates/
+        my-template.ftl
+        ...
+    jbake.properties
+    pom.xml
+----
+
+Run `mvn generate-resources` and open `my-project/target/website/index.html` in a browser to see the result.
+
+=== Goals (maven plugin)
+
+There are 4 goals provided by the maven plugin:
+
+* `jbake:seed` - seeds your project/site with example content and templates
+* `jbake:generate` - bakes your project/site
+* `jbake:watch` - watches to changes and bakes your site whenever a change is detected
+* `jbake:inline` - bakes, watches and serves out content on http://localhost:8820[http://localhost:8820]
+
+Get more details on each goal by running the help goal:
+
+----
+$ mvn jbake:help -Ddetail # -DgoalName=[seed|generate|watch|inline]
+----
+
 == Gradle Plugin
 
 There is a http://gradle.org/[Gradle] plugin that allows you to run JBake from your Gradle build.

diff --git a/content/download.adoc b/content/download.adoc
@@ -68,7 +68,7 @@ JBake artifacts are available from the Maven central repository:
 <dependency>
 	<groupId>org.jbake</groupId>
 	<artifactId>jbake-core</artifactId>
-	<version>2.6.7</version>
+	<version>${jbakeVersion}</version>
 </dependency>
 ----
 

diff --git a/content/news/jbake-v2.7.0-release-candidate.adoc b/content/news/jbake-v2.7.0-release-candidate.adoc
@@ -11,7 +11,53 @@ Jonathan Bullock
 
 We're getting close to the release of JBake v2.7.0, and given the scale of code changes that have been made recently we thought it was prudent to make a release candidate available.
 
-So JBake v2.7.0-rc.2 is now available from https://github.com/jbake-org/jbake/releases[GitHub Releases]
+So JBake v2.7.0-rc.5 is now available from https://github.com/jbake-org/jbake/releases[GitHub Releases]
 
 We'd be really grateful if you could try this release candidate out against any JBake sites/projects you have. If you encounter any issues please https://github.com/jbake-org/jbake/issues[let us know] so we can address them prior to the final release of v2.7.0
 
+=== Important changes
+
+==== JBake Maven Plugin (v2.7.0-rc.6 or higher)
+
+The JBake Maven plugin version is now aligns to the JBake version
+and includes all optional JBake core dependencies.
+Every JBake release now also includes a jbake-maven-plugin release.
+
+This makes it easier to upgrade JBake: no need to align the dependencies any more.
+It is now also easy to see which JBake version you're actually using.
+
+Before in `pom.xml`:
+
+----
+      <plugin>
+        <groupId>org.jbake</groupId>
+        <artifactId>jbake-maven-plugin</artifactId>
+        <version>0.3.5</version><!-- 0.3.5 uses JBake 2.6.7 -->
+        ...
+        <dependencies>
+          <dependency>
+            <groupId>org.asciidoctor</groupId>
+            <artifactId>asciidoctorj</artifactId>
+            <version>2.4.3</version><!-- Adjust when upgrading JBake -->
+          </dependency>
+          <dependency>
+            <groupId>org.freemarker</groupId>
+            <artifactId>freemarker</artifactId>
+            <version>2.3.31</version><!-- Adjust when upgrading JBake  -->
+          </dependency>
+          ...
+        </dependencies>
+      </plugin>
+----
+
+After in `pom.xml`:
+
+----
+      <plugin>
+        <groupId>org.jbake</groupId>
+        <artifactId>jbake-maven-plugin</artifactId>
+        <version>2.7.0</version><!-- Same as JBake version -->
+        ...
+        <!-- No need to maintain transitive dependencies -->
+      </plugin>
+----
diff --git a/jbake.properties b/jbake.properties
@@ -1,3 +1,5 @@
+jbakeVersion=2.6.7
+
 template.folder=templates
 content.folder=content
 asset.folder=assets
@@ -11,4 +13,4 @@ render.tags=false
 tag.path=tags
 site.host=http://jbake.org
 template.news.file=news.ftl
-#db.store=local
+#db.store=local