Apache Apex Incubator Website

This is the source code for the Apache Apex Incubator website, hosted at apex.incubator.apache.org. The following tools are used to build the html pages:

• nodejs + npm
• gulp - nodejs automation tool
• handlebars.js - templating
• LESS - css pre-processor
• Marked - Markdown parser/compiler
• Bootstrap - HTML/CSS/JS framework
• jQuery
• HighlightJS - code syntax highlighting

How it works

The master branch of this repo contains the source files that are used to generate the HTML that ultimately gets pushed to the incubator site. The asf-site branch is where the actual generated files are stored. Note that this branch must contain exactly one folder called content, and so has been checked out as an orphan branch with its own commit history apart from the master branch. See the Contributing section below.

Through a gitpubsub mechanism on the apache.org server, files are taken from the asf-branch and pushed to the live server.

Pages

Pages are stored in the src/pages folder. Each page uses the handlebars templating engine, and should look something like this:

{{> header}} <!-- includes the header.handlebars partial -->

<h1>Hello World</h1>
<p>I am a page.</p>

{{> footer}} <!-- includes the footer.handlebars partial -->

Partials

All pages on the site share the same header and footer. These are stored in the src/partials folder. You can put other partials in here and they will be made available to all templates (the .handlebars extension is dropped).

Markdown files

If you have a block of content that you would like to render from a markdown file, you can do so by creating a .md file in the src/md/ folder. These .md files will be picked up, rendered has html, and exposed to page templates as partials. Assuming you have a file called src/md/example_markdown.md, you could have this in a page template:

{{> header}}

<h1>Page with Injected Markdown</h1>

{{> example_markdown}}

{{> footer}}

Contributing

If you would like to make a change to the site:

1. Fork the github mirror
2. Create a new branch from master
3. Add commit(s) to your branch
4. Test your changes locally (see Development section below)
5. Open a pull request on the github mirror
6. A committer will merge your changes if all is good

If you are a committer, do the following:

1. Update the master branch with your (or a Pull Request's) change.
2. Push updated master to the asf remote master (https://git-wip-us.apache.org/repos/asf/incubator-apex-site.git)
3. Run build.sh from the master branch directory (requires nodejs and npm). This will:

• ensure the necessary npm and bower dependencies are installed
• checks out and updates the asf-site branch with a new commit of the build from the current branch

3. At this point, you should be on the asf-site branch. Simply push this branch to the asf remote and the site will automatically be updated within seconds.

Development

First, install dependencies:

npm install
./node_modules/.bin/bower install

To test changes:

1. Make your changes to .md, .html, and .less files
2. Run ./node_modules/.bin/gulp. This creates a content folder
3. Serve this folder using something like Python's Simple HTTP Server.
4. View the changes on the server you started in the previous step

One way to improve this process is to run ./node_modules/.bin/gulp watch. This will start a process that watches for changes to source files and updates the /content folder accordingly. This way you make your change and refresh the page to see the effect immediately.

Updating Downloads Page

The downloads page uses the content of ./releases.json to populate the tables found there. Care has been taken to automatically generate this releases.json file. To do so, run:

./node_modules/.bin/gulp fetch-releases
git add releases.json
git commit -m 'updated releases'

This will do the following things:

1. Parses out the release versions available via the ASF dist pages.
2. Queries Github for these found release tags to find the date they were published to github
3. Writes to releases.json with release information.

Once you have committed the changes to releases.json, follow the steps to contributing steps to publish the site to go live.