This repository contains the source of the Forge website.

The website is built using Awestruct. The develop branch contains the unprocessed website source. From that content, Awestruct generates a static website under the _site directory. The website is published to the public site by pushing the contents of the _site directory to the master branch.

You need to have Awestruct installed on your machine to preview the website locally. Awestruct is a available as Ruby gem in the GemCutter repository. You can install it into either a native Ruby or a JRuby installation. The instructions here will cover setting up Awestruct in both native Ruby and JRuby installation for Linux environment.

Begin by installing the package for Ruby and RubyGems.

The easiest way to set up Ruby and RubyGems on MacOs is to use JewelryBox, which is a UI for RVM. From here you can install versions of Ruby and manages Gemsets. Of course you can do this from the command line too.

If you have Ubuntu, use this command to install Ruby and RubyGems:

$ sudo apt-get install rubygems

Ubuntu does not currently add the RubyGems bin directory to your path. Put the following files in your shell configuration file (.bashrc) and restart the shell.

$ export GEM_HOME=/var/lib/gems/1.8 \ 
export PATH=$PATH:$GEM_HOME/bin

Now the executables for any gem you install will be available on your path.

It might happen that you will face similar problem while trying to install awestruct using Ruby on Ubuntu. In that case using JRuby as an alternative might solve it.

First, download and unpack latest stable version of JRuby: (The one available in Ubuntu repositories is too old and does not support Awestruct)

$ wget http://jruby.org.s3.amazonaws.com/downloads/1.6.5/jruby-bin-1.6.5.tar.gz \
tar -xzvf jruby-bin-1.6.5.tar.gz  

Optionally, you can copy it to /usr/lib/jvm and create symbolic link for convenience:

$ sudo mv jruby-1.6.5/ /usr/lib/jvm \
cd /usr/lib/jvm/ \
sudo ln -s jruby-1.6.5/ jruby 

Last step is adding JRuby to path (for instance in .bashrc)

$ export JRUBY_HOME=/usr/lib/jvm/jruby \
export PATH="$JRUBY_HOME/bin:$PATH"

That’s it. Just install all required gems described in subsequent sections and you are ready to run awestruct backed by JRuby!

NOTE: Use jgem instead of sudo gem for this purpose.

If you have Fedora, use this command to install Ruby and RubyGems:

$ sudo yum install ruby ruby-devel ruby-irb rubygems

Optionally, you can install RubyGems manually to use a newer version (was once a requirement for installing Awestruct, but has since been fixed):

$ wget -q http://production.cf.rubygems.org/rubygems/rubygems-1.8.15.tgz \
tar xzf rubygems-1.8.15.tgz \
cd rubygems-1.8.15 \
sudo ruby setup.rb

In Fedora, RubyGems properly links applications such as awestruct to /usr/bin when the corresponding gem is installed, so no need for messing with the PATH.

Now you are ready to install awestruct. The remainder of the commands work on any Ruby installation. If you’re using JRuby, remember to use jgem instead of sudo gem.

Use this command to install the awestruct gem and its dependencies:

$ sudo gem install awestruct

If you get a compiler error when RedCloth is installing, use this command instead:

$ sudo gem install awestruct -- --with-cflags=\"-O2 -pipe -march=native -Wno-unused-but-set-variable\"

You’re all set!

If you’ve previously installed awestruct, make sure you have Awestruct >= 0.2.5. You can update it update it using this command:

$ sudo gem update awestruct

NOTE: Make sure you are using RedCloth-4.2.9 to properly support international characters in guides.

As the website matures, more gems will be required. This section documents the required third-party gems not already installed by Awestruct.

Install these Gems using the sudo gem install command (or jgem install command for JRuby) as you did above.

• rest-client
• git
• sassy-buttons
• vpim
• json
• jruby-openssl (if using jruby)
• rb-inotify (if using linux)

Now there’s an even easier way to get setup. First, make sure you have the Bundler gem installed:

$ sudo gem install bundler

Now Bundler can handle the rest of the setup automatically:

$ sudo bundle install

At this point, you are ready to pull down the site and run it.

Now that you have awestruct installed, you can preview the website locally by running it in development mode. Development mode uses a file monitor to automatically update the site when you make a change to the source files.

To run the site, you first need the source code. Begin by cloning the website source code from git:

git clone git://github.com/forge/forge.github.com.git

Then, switch to the develop branch (the master branch holds the published site only):

git checkout develop

Run the following command to launch the preview server:

awestruct -d

Visit the following page in your browser:

http://localhost:4242

You’re now awestruct!

If you only want to generate once when you start the server, use this command:

awestruct --server -P development

Add the --force flag to either command to regenerate the site from scratch. You can also remove the _tmp and _site directories to clean the generated files.

Haml is the preferred abstract HTML markup language.

• Haml Reference

• Textile Reference

Source files are indented using 2 spaces. Haml files require the same indentation size throughout. Ruby hashes should have no leading or trailing spaces and options such be seperated by a comma followed by a space (e.g., {:href=>"http://jboss.org/forge", title=>"Forge Project Site"}).

Note: In a HAML document, if you use the equals seperator (=) rather than a greater than equals (=>) in a hash key-value assignment, Awestruct will crash.

Contribution documentation is very easy. You simply create a new .textile file in one of the /docs sub directories. The directory structure is used to structure documentation. At the top of the file you should add some prolog and your documentation page will show up in the menu automatically.

The prolog is a set of name/value pairs defined at the top of the file in between two lines containing three dashes. In this section you define the following metadata:

• layout (always “docs”)
• title (use sentence capitalization)
• author

Here’s an example (refer to HTML output):

---
layout: docs
title: Writing docs
author: Paul Bakker
--- << only copy the hyphens and the lines of text between them

Below the prolog, you just type in textile format.

NOTE: Please follow the JBoss Community syntax conventions when formatting the code (to ensure all posts look consistent).

To insert syntax highlighted code, followed by paragraph text, use the following syntax (refer to HTML output of this guide):

public class Alien {
    public String getName() {
        return "Ike";
    }
}

This sentence will appear below the code. The language is detected automatically.

You don’t normally need to use the p. prefix to enter a paragrah. However, it’s required after a code block to indicate to the parser that the code snippet has ended. If the content following the code is not paragraph text (for instance, a list item), use notextile. instead of p., but include one space at the end of the line.