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

Most of the site sources are in plain markdown, more specifically in python-markdown.

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:

   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:

   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.

   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 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, then refer to the STATUS file. You'll of course also need a local clone of the site sources, or even preferably a local clone of github's mirror, 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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

#!/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 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...)
4. 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 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¶

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