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.
