General

Releases

Development

Community

Developer Resources

Archive

Apache Foundation

Velocity News Feed

the Apache Velocity Site

Introduction

The Apache Velocity Site is what you get when you visit our homepage. It is the envelope site for all Apache Velocity sub projects.

In short: This svn repository is only interesting for you if you

  • want to re-create the Apache Velocity site on your local computer or intranet.
  • are an Apache Velocity committer and want to update the site.

Editing the Site

Apache Velocity uses the Apache Content Management System to manage its site.

For the time being, the site is not yet hosted by the CMS (which is not yet accepting new sites before undergoing a machine transition), so the site still has to be build locally. Please refer to the next section. The rest of this section is not yet applicable.

To just edit one page, all you need is the bookmarklet found here

If you're a commiter, you'll be able to push your edits by yourself on the production site. Otherwise, the CMS will let you generate a diff file that you can send to the devs.

Commiters can also commit changes to the site under svn and trigger a publication in production from the CMS.

Building the Site

To build the site locally, you'll need a local checkout of the Apache CMS, then refer to the STATUS file. You'll of course also need a local checkout of the site sources (the sources for the cms are in /cms/, but the process needs the whole site).

While Velocity isn't yet hosted on the CMS, you'll have to generate the site in velocity/site/production, then check added/modified/deleted files with svn status, and commit the result.

Typically, you'll have to:

  1. define the environment variable MARKDOWN_SOCKET to something like /tmp/markdown
  2. launch the CMS markdown daemon apache-cms/build/markdownd.py
  3. run apache-cms/build/build_site.pl --source-base velocity/site/cms/trunk --target-base velocity/site/target (adapt the paths)
  4. copy the generated files from site/target/content to site/production (including the hidden file site/target/.htaccess)
  5. check the result then commit

Here's a bash script that you can reuse:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
#!/bin/bash

export MARKDOWN_SOCKET=/tmp/markdown
CMS=~/projects/velocity/apache_cms
VELOCITY=~/projects/velocity

if [[ `pidof markdownd.py` == "" ]]; then
   $CMS/build/markdownd.py
fi

find $VELOCITY/site/cms/trunk/ -name "*~" | xargs rm -v
rm -rf $VELOCITY/site/target

$CMS/build/build_site.pl --source-base $VELOCITY/site/cms/trunk --target-base $VELOCITY/site/target
cp -r $VELOCITY/site/target/content/* $VELOCITY/site/production/
cp $VELOCITY/site/target/content/.htaccess $VELOCITY/site/production/

svn status $VELOCITY/site/production/

Notes:

  • the markdown tables extension, in the python-markdown package (python 2.7), seems broken at version 2.6.9 ; I had to revert the markdown package to 2.6.7.
  • the python pygments lexer (used by markdown/codehilite for code syntax highlighting) knows about the Velocity syntax, but not about silent references like $!foo or $!{bar}. I patched it and sent the patch upstream.

Additional Notes

Table of Content

Per-page table of contents can be displayed with the following placeholder:

[TOC]

Tables

Tables are supported. See the documentation of the python-markdown extension.

Syntax highlighting

The markdown module used by the CMS allows one to specify which language lexer to use for syntax coloring of blocks of code, using the following syntax:

:::velocity
#set( $foo = 'bar' )
...

which produces:

#set( $foo = 'bar' )
 ...

There are many lexers available, among which :::java, :::html, :::xml, :::properties, :::velocity, :::html+velocity, :::xml+velocity, etc.

Breadcrumbs use the full pathname of the file (one path per level). So choose filenames and structure apropriately, as directory names will be used to label each step.

Left Navigation

The deepest left.nav (markdown format) will be used (starting from the current page markdown script directory and going up the hierarchy).

Post-Processing

To be able to handle some specific dynamic parts of the site that depends upon other resources than their markdown file (aka news, contributors, changes...), a post-processing mechanism has been setup:

  1. define a perl subroutine in lib/view.pm called "my_specific_section" (for instance) that returns a string
  2. in the markdown file, use a {{my_specific_section}} tag wherever needed
  3. in path.pm, make sure that "postprocessing => 1" is included in the parameters relative to this markdown file

The perl subroutine will be called after the markdown has been processed into html. The process is recursive: the result of a post-processing tag can contains other tags.

TODO

Integration of several Maven reports: dependency-convergence - subversion changelog - dev-activity - file-activity...