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

Most of the site sources are in plain markdown, more specifically in [python-markdown](https://python-markdown.github.io/).

### Building the site with docker

This method is by far the easiest one.

1. Clone the site sources
    
    If you are a Velocity commiter, you will want to directly edit the site sources:
    
        :::shell
        git clone https://github.com/apache/velocity-site.git
    
    If you are a contributor, you should first fork the site sources to your github account, and use:
    
        :::shell
        git clone --single-branch --branch main git@github.com:[YOUR_GITHUB_ID]/velocity-site.git

2. Clone the site production pages
    
    As a commiter you will use it to push into production the generated site. As a contributor, you will use it to check locally the result of your changes.
    
    This clone must be called `velocity-site-prod` and must be made in the same directory as the `velocity-site` one.
    
        :::shell
        git clone --single-branch --branch asf-site https://github.com/apache/velocity-site.git velocity-site-prod

3. Make your changes to the site sources

4. Run the script `velocity-site/builder/bin/builder.sh` (linux implied...)

5. Check the result using your favorite browser

6. Advertize your changes
    
    Commiters have to push the changes in both clones, the source and the production one. Contributors only need to submit a pull request to the site sources.

### Building the site without docker

Apache Velocity uses the [Apache Content Management System](https://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.

To do so, 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