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