Sections

  1. Building the guides
  2. Creating a HOWTO
  3. Customising the styling
  4. Community

Contribute to these guides

These HOWTO guides are built from a source project hosted on GitHub that anyone is free to contribute to. Contributions can take the form of modifications to existing guides, the addition of new ones, or changes to the styling of the published HOWTOs.

If you would like to contribute, simply send an internal GitHub message to 'pledbrook' requesting commit access. It's not obvious how to do this in GitHub, but basically you click the Compose Message link on your inbox/notifications page:

and then add the 'pledbrook' handle to the recipient field:

Once access has been granted, you will be able to commit directly to the project repository .

Building the guides

Once you have cloned the repository locally, all you have to do is run


./gradlew docs

from the root of the project. This will generate all the HOWTO guides in all the languages inside the build/docs directory. If you would like to generate only the guides for a particular language, simply add the language suffix. For example,


./gradlew docs_fr

will generate the French HOWTO guides but no others.

Creating a HOWTO

All the guides are standalone gdoc files that reside under the src/$lang directories. So, to add a 'Deploy to JBoss' English HOWTO, you would simply create the file 'src/en/deployToJboss.gdoc' and add the HOWTO content to it.

The only requirements for each HOWTO gdoc file are that:

  1. the first line is an h1. heading, which becomes the title of the HOWTO; and
  2. h2. is used for the top-level sections.

For example, a very basic gdoc would look like:

h1. Deploy to JBoss
Introduction to this guide
h2. The basics
...

Links between HOWTOs are not supported at this moment in time, but external links are the same as for standard gdoc syntax.

As soon as you create the gdoc file, it will be picked up automatically by the build the next time you run the docs task. The resulting HTML file will have the same base name as the gdoc file, for example 'deployToJboss.html'.

If you wish to add an image to a HOWTO, place the file in the 'resources/img' directory and insert an entry like !<path to image>! into the gdoc source. For example, if you have the image 'resources/img/deployToJboss/deployCycle.png' then link to it using the syntax:


!deployToJboss/deployCycle.png!

Note that the path specified inside the exclamation marks is relative to the 'resources/img' directory.

Customising the styling

The HTML layout for the HOWTO guides is defined in the file 'resources/templates/how-to-template.html'. Static resources required by the template, such as images and stylesheets, should be placed in the respective directory under 'resources/img', 'resources/css' and 'resources/js' as appropriate.

When adding links to static resources inside the template, be sure to use the resourcesPath variable like so:

<link href="${resourcesPath}/css/main.css" type="text/css" ...>

This ensures that the template works regardless of whether the generated guide is in a language-specific directory or not.

Community

This is an open repository allowing anyone who's interested to contribute. On the flip side, there is no central editorial control, so contributors are expected to police the system themselves to prevent abuse.