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

The site is not *hosted* by the CMS (it's planned to move it to pelican), so it still has to be build locally.

### 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 clone of [the site sources](https://gitbox.apache.org/repos/asf/velocity-site.git), or even preferably a local clone of [github's mirror](https://github.com/apache/velocity-site.git), where you can submit pull requests.

You'll have to generate the site in some `target` temporary directory, then check added/modified/deleted files in the `asf-site` branch of the `velocity-site` repository.

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/src --target-base /tmp/target` (adapt the paths)
4. copy the generated files from `target` to velocity-site's asf-site branch (including the hidden file .htaccess)
5. check the result then commit and push

Here's a bash script that you can adapt and reuse:

    #!/bin/bash
    
    export MARKDOWN_SOCKET=/tmp/markdown
    CMS=~/projects/velocity/apache_cms
    VELOCITY=~/projects/velocity/git
    
    if [[ `pidof markdownd.py` == "" ]]; then
       $CMS/build/markdownd.py
    fi
    
    find $VELOCITY/velocity-site/src/content -name "*~" | xargs rm -v
    rm -rf $VELOCITY/velocity-site-target/* rm -rf $VELOCITY/velocity-site-target/.htaccess

    echo Generating site...

    $CMS/build/build_site.pl --source-base $VELOCITY/velocity-site/src --target-base $VELOCITY/velocity-site-target

    echo Copying to production directory...

    rm -rf $VELOCITY/velocity-site-prod/* $VELOCITY/velocity-site-prod/.htaccess
    cp -r $VELOCITY/velocity-site-target/content/* $VELOCITY/velocity-site-prod/
    cp -r $VELOCITY/velocity-site-target/content/.htaccess $VELOCITY/velocity-site-prod/

    echo Post processing...

    find $VELOCITY/velocity-site-prod/ -name "*.html" | xargs sed -ri -e "s'<span></span>''g"

    cd $VELOCITY/velocity-site-prod
    echo cd $VELOCITY/velocity-site-prod
    pwd
    git status

Notes:

* 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, which has been accepted but not yet released at the time of writing.

### 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, like dependency-convergence