Author: cbrisson Date: Tue Jun 26 12:11:54 2018 New Revision: 1834420 URL: http://svn.apache.org/viewvc?rev=1834420&view=rev Log: [site] Supress redundant README and update site building page
Removed: velocity/site/cms/trunk/content/README Modified: velocity/site/cms/trunk/content/css/site.css velocity/site/cms/trunk/content/site-building.mdtext Modified: velocity/site/cms/trunk/content/css/site.css URL: http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/css/site.css?rev=1834420&r1=1834419&r2=1834420&view=diff ============================================================================== --- velocity/site/cms/trunk/content/css/site.css (original) +++ velocity/site/cms/trunk/content/css/site.css Tue Jun 26 12:11:54 2018 @@ -278,6 +278,13 @@ pre, code padding: 3px 3px; } +.grayed +{ + color: darkgray; + font-style: italic; + text-decoration: strike-though; +} + /* tables */ table.standard, table.table Modified: velocity/site/cms/trunk/content/site-building.mdtext URL: http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/site-building.mdtext?rev=1834420&r1=1834419&r2=1834420&view=diff ============================================================================== --- velocity/site/cms/trunk/content/site-building.mdtext (original) +++ velocity/site/cms/trunk/content/site-building.mdtext Tue Jun 26 12:11:54 2018 @@ -2,7 +2,7 @@ Title: Apache Velocity - Site Building ## the Apache Velocity Site -WARNING! This document might be out of date! For the latest information on how to build the Apache Velocity Site, please check out the actual [README](/README) file which contains the latest information. This document has been created from the README and is not updated as often. +[TOC] ### Introduction @@ -20,14 +20,20 @@ Apache Velocity uses the [Apache Content 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) (check the [STATUS](https://svn.apache.org/repos/infra/websites/cms/STATUS) file) and of course a local checkout of [Velocity's site sources](https://svn.apache.org/repos/asf/velocity/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: @@ -58,8 +64,39 @@ Here's a bash script that you can reuse: 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 +#### 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.