ingenieux Labs - JBake Maven Plugin Walkthough

JBake Maven Plugin Walkthough

This walkthough covers the bare essentials from creating a JBake site hosted in
either Amazon S3 or Github Pages,
using Cloud9 as your Development Enviroment

Prerequisites

You need:

An account in Cloud9. This also works on other environments, like Koding
Basic Apache Maven Skills
A repository in Github

Caveats

Currently, .github.io is not supported on github pages. We're trying to find an interesting solution

Creating the Basic Project

On Github, fork the jbake-sample repo
Create a new project in cloud9 using "Create from Workspace" | "Create a new Workspace":
- type: Custom
Open a new shell session. Install mvm:
$ curl https://raw.github.com/ingenieux/mvm/master/install.sh | sh
$ source ~/.mvm/mvm.sh
$ mvm install 3.1.1
$ mvm alias default 3.1.1

Once finished, restart the shell session (type exit - it will respawn a new one)

Import the sources (replace the Git URL below):
$ git init
$ git add origin ssh://git@github.com/ingenieux/jbake-sample.git
$ git pull origin master

Running a Stage Copy:

On Cloud9, you need to bind the port and the host. Use this command:
$ mvn jbake:inline -Djbake.port=$PORT -Djbake.listenAddress=$IP

That done, you could access it as http://..c9.io/. E.g., for aldrinleal/jbake_sample (locally on c9 as ingenieux_github.io), it is http://jbake_sample.aldrinleal.c9.io.

Mojo Parameters

There are 4 goals:

* jbake:generate: Simply runs jbake
* jbake:watch: polls a folder and run jbake whenever changes happen
* jbake:inline: Same as watch, but also launches an embedded winstone container

For more details, run:

$ mvn jbake:help -Ddetail # -DgoalName=[watch|generate|inline]

Publishing Options

Amazon S3

The defaults use Amazon S3. In order to enable publishing, create a Server Settings with the the AWS Access Key Id as username and the Secret Access Key as a password.

Start by creating your settings.xml as shown in Configuring your AWS Credentials. Long story short:

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                      http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <servers>
    <server>
    <id>yours3site</id>
      <username>022QF06E7MXBSH9DHM02</username>
      <password>{2A16DoTRdiUHn7djDvmu4O1E1JrYg5avldQ3Khv8B4jk4MzLpzJeSrabGG8aBSSfa3b2PAvfLvVCwsl0MaRmmA==}</password>
    </server>
  </servers>
</settings>

Then, change the pom.xml with it (see elements '' and ''):

<configuration>
    <fromDir>${project.build.directory}/${project.build.finalName}</fromDir>
    <includes>**/*</includes>
    <excludes>**/*.jsp,**/web.xml</excludes>
    <url>s3://docs.ingenieux.com.br</url>
    <serverId>docs.ingenieux.com.br</serverId>
</configuration>

Of course, you need your extra S3 setup in place, which means:

Having the bucket created
... as well as with S3 Access
CNAME created (or Route 53 alias)

To publish, simply use this command:

$ mvn verify

Github Pages

Github offers a maven plugin. So we only need to enable it by adding that to your settings.xml as shown in their docs. Example:

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                      http://maven.apache.org/xsd/settings-1.0.0.xsd">
    <servers>
        <server>
            <id>github</id>
            <username>aldrinleal</username>
            <password>password</password>
        </server>
    </servers>
</settings>

In your pom.xml, remove the wagon plugin definition and use this instead:

<plugin>
  <groupId>com.github.github</groupId>
  <artifactId>site-maven-plugin</artifactId>
  <version>0.9</version>
  <configuration>
    <message>Creating site for ${project.version}</message>
    <outputDirectory>${project.build.directory}/${project.build.finalName}</outputDirectory>
    <repositoryName>jbake-sample</repositoryName>
    <repositoryOwner>ingenieux</repositoryOwner>
    <excludes>
        <exclude>**/*.jsp</exclude>
        <exclude>**/web.xml</exclude>
    </excludes>
  </configuration>
  <executions>
    <execution>
      <goals>
        <goal>site</goal>
      </goals>
      <phase>verify</phase>
    </execution>
  </executions>
</plugin>

Add this as well:

<properties>
    <github.global.server>github</github.global.server>
</properties>

Adding support for:

Syntax Highlighting

We use syntaxhighlighter which covers most of the needs. See those two lines in header.ftl:

<link rel="stylesheet" href="http://yandex.st/highlightjs/7.3/styles/default.min.css">
<script src="http://yandex.st/highlightjs/7.3/highlight.min.js"></script>

On footer.ftl, we activate it:

<script type="text/javascript">
  $(function() {
    hljs.tabReplace = '  '; //4 spaces
    hljs.initHighlighting();
  });
</script>

Disqus

Disqus is set in header.ftl:

<#if (content)?? && (content.disqus)??>
  <!-- disqus stuff -->    
  <script type="text/javascript">
  /* * * CONFIGURATION VARIABLES: EDIT BEFORE PASTING INTO YOUR WEBPAGE * * */
  var disqus_shortname = 'ingenieux-docs'; // required: replace example with your forum shortname

  /* * * DON'T EDIT BELOW THIS LINE * * */
  (function() {
      var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
      dsq.src = '//' + disqus_shortname + '.disqus.com/embed.js';
      (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
  })();
  </script>
  <noscript>Please enable JavaScript to view the <a href="http://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
  <a href="http://disqus.com" class="dsq-brlink">comments powered by <span class="logo-disqus">Disqus</span></a>
  <!-- /disqus stuff -->
</#if>

In order to allow disqus com a single page, make sure you enable disqus=true. Example (skel.md):

title=title
date=2013-10-11
type=page
status=published
disqus=true
~~~~~~

RSS Feeds

Tweak feed.ftl and custom.properties files

Google Analytics

Simply add the qa script (or change the supplied one with the Tracking ID) on footer.ftl:

<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-32618923-2', 'ingenieux.com.br');
ga('send', 'pageview');
</script>

ingenieux docs