cms/trunk/content/site-building.mdtext

Title: Apache Velocity - Site Building

## the Apache Velocity Site

[TOC]

### 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](/who-we-are.html) and want to update the site.

### Editing the Site

Apache Velocity uses the [Apache Content Management System](http://www.apache.org/dev/cms.html) 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](https://cms.apache.org/#bookmark)
{.grayed}

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](/contact.html).
{.grayed}

Commiters can also commit changes to [the site under svn](http://svn.apache.org/repos/asf/velocity/site/cms/trunk/) and trigger a publication in production from the CMS.
{.grayed}

### Building the Site

To build the site locally, you'll need a local checkout of the [Apache CMS](https://svn.apache.org/repos/infra/websites/cms), then refer to the [STATUS](https://svn.apache.org/repos/infra/websites/cms/STATUS) file.
You'll of course also need a local checkout of [the site sources](https://svn.apache.org/repos/asf/velocity/site) (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:

    #!/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](https://bitbucket.org/birkenfeld/pygments-main/pull-requests/771/add-velocity-silent-references-syntax/diff) upstream.

### Additional Notes

### Javadocs

For the time being, here are the steps to build the javadocs (listed for the engine, adapt for the tools):

1. issue an `mvn javadoc:aggregate -pl !velocity-custom-parser-example` command at the root of the source tree (the `-pl` option is here to ignore a specific module from the docs)
2. copy the content of the `target/site/apidocs` directory inside of the `apidocs` directory of the apropriate module inside the site sources
3. commit this result (which will produce a first big fat commit email...)
3. generate the site then commit the production result (second horrible commit email...)

#### 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](https://python-markdown.github.io/extensions/tables/) 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:

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

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

#### Breadcrumbs

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...