documentation/development/site-how-to.html - felix-site-pub - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
 <html>
 <!--

     Licensed to the Apache Software Foundation (ASF) under one or more
     contributor license agreements.  See the NOTICE file distributed with
     this work for additional information regarding copyright ownership.
     The ASF licenses this file to You under the Apache License, Version 2.0
     (the "License"); you may not use this file except in compliance with
     the License.  You may obtain a copy of the License at

        https://www.apache.org/licenses/LICENSE-2.0

     Unless required by applicable law or agreed to in writing, software
     distributed under the License is distributed on an "AS IS" BASIS,
     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     See the License for the specific language governing permissions and
     limitations under the License.
 -->
   <head>
     <title>Apache Felix - Site How To</title>
     <link rel="icon" href="/res/favicon.ico">
     <link rel="stylesheet" href="/res/site.css" type="text/css" media="all">
     <link rel="stylesheet" href="/res/codehilite.css" type="text/css" media="all">
     <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
   </head>
   <body>
     <div class="title">
       <div class="logo">
         <a href="https://felix.apache.org/">
           <img border="0" alt="Apache Felix" src="/res/logo.png">
         </a>
       </div>
       <div class="header">
         <a href="https://www.apache.org/">
           <img border="0" alt="Apache" src="/res/apache.png">
         </a>
       </div>
     </div>

     <div class="menu">
       <style type="text/css">
 /* The following code is added by mdx_elementid.py
    It was originally lifted from http://subversion.apache.org/style/site.css */
 /*
  * Hide class="elementid-permalink", except when an enclosing heading
  * has the :hover property.
  */
 .headerlink, .elementid-permalink {
   visibility: hidden;
 }
 h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
 <p><a href="/news.html">News</a>  <br />
 <a href="/license.html">License</a>  <br />
 <a href="/downloads.cgi">Downloads</a>  <br />
 <a href="/documentation.html">Documentation</a>  <br />
 <a href="/documentation/community/project-info.html">Project Info</a>  <br />
 <a href="/documentation/community/contributing.html">Contributing</a>  <br />
 <a href="/sitemap.html">Site Map</a>  <br />
 <a href="https://www.apache.org/">ASF</a>  <br />
 <a href="https://www.apache.org/security/">Security</a>  <br />
 <a href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a>  <br />
 <a href="https://www.apache.org/foundation/thanks.html">Sponsors</a>    </p>
 <iframe
     src="https://www.apache.org/ads/button.html"
     style="border-width:0; float: left"
     frameborder="0"
     scrolling="no"
     width="135"
     height="135">
 </iframe>
     </div>

     <div class="main">
       <div class="breadcrump" style="font-size: 80%;">
         <a href="/">Home</a>&nbsp;&raquo&nbsp;<a href="/documentation.html">Documentation</a>&nbsp;&raquo&nbsp;<a href="/documentation/development.html">Development</a>
       </div>

       <h1>Site How To</h1>
       <style type="text/css">
 /* The following code is added by mdx_elementid.py
    It was originally lifted from http://subversion.apache.org/style/site.css */
 /*
  * Hide class="elementid-permalink", except when an enclosing heading
  * has the :hover property.
  */
 .headerlink, .elementid-permalink {
   visibility: hidden;
 }
 h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
 <p>The site is managed with the <a href="https://www.apache.org/dev/cms.html">Apache CMS</a>
 where the source is kept in SVN at <a href="https://svn.apache.org/repos/asf/felix/site/trunk/content">https://svn.apache.org/repos/asf/felix/site/trunk/content</a>.</p>
 <h2 id="to-update-the-documentation-using-the-cms-system">To update the documentation using the CMS system<a class="headerlink" href="#to-update-the-documentation-using-the-cms-system" title="Permanent link">&para;</a></h2>
 <ul>
 <li>Install the bookmarklet from the <a href="https://cms.apache.org/">cms</a> page. You only have to do this once.</li>
 <li>Navigate to the page you wish to edit (on the live site, not in the cms).</li>
 <li>Click the bookmarklet. There will be a short pause while the CMS system is initialised for you.</li>
 <li>Click on <code>Edit</code> (to skip this step hack the bookmarklet to add an 'action=edit' param to the query string)</li>
 <li>The page editor should then be displayed.</li>
 <li>Click <code>Submit</code> to save your edit to the workarea</li>
 <li>Click <code>Commit</code> to save the updated file to SVN and trigger a staged build. (to skip this step click on the "Quick Commit" checkbox in the <code>Edit</code> form).</li>
 <li>The results should appear shortly on the <a href="http://felix.staging.apache.org/content/documentation.html">staging</a> site. (You may have to force the page to refresh in order to see the updated content)</li>
 <li>Once you are happy with the updated page, click on <code>Publish Site</code> to deploy.</li>
 </ul>
 <p>There is also a <a href="https://www.apache.org/dev/cmsref.html">Reference Manual</a> of the Apache CMS as well as a
 video tutorial at <a href="http://s.apache.org/cms-tutorial">http://s.apache.org/cms-tutorial</a>.</p>
 <h2 id="features-of-the-apache-felix-site">Features of the Apache Felix Site<a class="headerlink" href="#features-of-the-apache-felix-site" title="Permanent link">&para;</a></h2>
 <p>This section lists some Apache Felix features to help with the maintenance
 of the site, such as automatic link generation.</p>
 <p>Start the file with a <code>Title:</code> line to define the page title and the first H1 tag:</p>
 <div class="codehilite"><pre><span class="n">Title</span><span class="o">:</span> <span class="n">Page</span> <span class="n">Title</span>

 <span class="n">Here</span> <span class="n">comes</span> <span class="n">the</span> <span class="n">content</span> <span class="n">separated</span> <span class="k">with</span> <span class="n">a</span> <span class="n">blank</span> <span class="n">like</span> <span class="n">from</span> <span class="n">the</span>
 <span class="n">header</span> <span class="o">...</span>
 </pre></div>


 <p>The last modification information from SVN (revision, committer, and
 date/time) is automatically added when the page is rendered</p>
 <p>Excerpts can be added to a page using the <code>Excerpt:</code> header:</p>
 <div class="codehilite"><pre><span class="n">Title</span><span class="o">:</span> <span class="n">Page</span> <span class="n">Title</span>
 <span class="n">Excerpt</span><span class="o">:</span> <span class="n">Summary</span> <span class="n">of</span> <span class="n">the</span> <span class="n">page</span> <span class="k">for</span> <span class="n">inclusion</span> <span class="k">in</span> <span class="n">other</span> <span class="n">pages</span><span class="o">;</span>
    <span class="n">continuation</span> <span class="n">of</span> <span class="n">the</span> <span class="n">excerpt</span> <span class="n">must</span> <span class="n">be</span> <span class="n">indented</span>

 <span class="n">Here</span> <span class="n">comes</span> <span class="n">the</span> <span class="n">content</span> <span class="n">separated</span> <span class="k">with</span> <span class="n">a</span> <span class="n">blank</span> <span class="n">like</span> <span class="n">from</span> <span class="n">the</span>
 <span class="n">header</span> <span class="o">...</span>
 </pre></div>


 <p>Metadata from child pages can be referred to in the content with the
 Django variable reference notation using the child page name (without
 extension) as its container; e.g. for the child page named <code>childpage</code>:</p>
 <div class="codehilite"><pre><span class="cp">{{</span> <span class="nv">children.childpage.headers.excerpt</span> <span class="cp">}}</span><span class="x"></span>
 <span class="cp">{{</span> <span class="nv">children.childpage.headers.title</span> <span class="cp">}}</span><span class="x"></span>
 </pre></div>


 <p>Content Pages can contain Django templates of the form <code>{{...}}</code> and <code>{%...%}</code>.
 If so, the page content is evaluated as a Django template before running
 it through the page template.</p>
 <p>Any page in the site can be referenced with refs.pagename returning properties:</p>
 <dl>
 <dt><code>.path</code></dt>
 <dd>the absolute path of the page on the site</dd>
 <dt><code>.headers</code></dt>
 <dd>page headers (e.g. <code>.title</code>, <code>.excerpt</code>)</dd>
 <dt><code>.content</code></dt>
 <dd>the raw page content</dd>
 </dl>
 <p>All pages in the children namespace are also available in the refs namespace</p>
 <p>Some usefull hints:</p>
 <p>Printing title of another page "handler":</p>
 <div class="codehilite"><pre><span class="x">   :::django</span>
 <span class="x">   </span><span class="cp">{{</span> <span class="nv">refs.handler.headers.title</span> <span class="cp">}}</span><span class="x"></span>
 </pre></div>


 <p>Printing excerpt of another page "handler":</p>
 <div class="codehilite"><pre><span class="x">   :::django</span>
 <span class="x">   </span><span class="cp">{{</span> <span class="nv">refs.handler.headers.excerpt</span> <span class="cp">}}</span><span class="x"></span>
 </pre></div>


 <p>Linking to another page "handler":</p>
 <div class="codehilite"><pre><span class="x">   :::django</span>
 <span class="x">   (</span><span class="cp">{{</span> <span class="nv">refs.handler.path</span> <span class="cp">}}</span><span class="x">)</span>
 </pre></div>


 <p>Printing title as a link to another page "handler":</p>
 <div class="codehilite"><pre><span class="x">   :::django</span>
 <span class="x">   [</span><span class="cp">{{</span> <span class="nv">refs.handler.headers.title</span> <span class="cp">}}</span><span class="x">](</span><span class="cp">{{</span> <span class="nv">refs.handler.path</span> <span class="cp">}}</span><span class="x">)</span>
 </pre></div>


 <p>Printing excerpt as a link to another page "handler":</p>
 <div class="codehilite"><pre><span class="x">   :::django</span>
 <span class="x">   [</span><span class="cp">{{</span> <span class="nv">refs.handler.headers.excerpt</span> <span class="cp">}}</span><span class="x">](</span><span class="cp">{{</span> <span class="nv">refs.handler.path</span> <span class="cp">}}</span><span class="x">)</span>
 </pre></div>


 <p>Print a bullet pointed child page list:</p>
 <div class="codehilite"><pre><span class="x">   :::django</span>
 <span class="x">   </span><span class="cp">{%</span> <span class="k">for</span> <span class="nv">label</span><span class="o">,</span> <span class="nv">page</span> <span class="k">in</span> <span class="nv">children</span> <span class="cp">%}</span><span class="x">* [</span><span class="cp">{{</span> <span class="nv">page.headers.title</span> <span class="cp">}}</span><span class="x">](</span><span class="cp">{{</span> <span class="nv">page.path</span> <span class="cp">}}</span><span class="x">)</span>
 <span class="x">   </span><span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span><span class="x"></span>
 </pre></div>


 <div class="note">
 It is important to have the first part as a single line, otherwise
 the Django/Markdown combo will create a list for each entry.
 </div>

 <h2 id="code-highlighting">Code Highlighting<a class="headerlink" href="#code-highlighting" title="Permanent link">&para;</a></h2>
 <p>Code Highlighting works by indenting code by four blanks. To indicate the
 type of highlighting preced the code style text with either <code>:::&lt;lexer&gt;</code> to
 get high lighted code using the given <code>&lt;lexer&gt;</code> or <code>#!&lt;lexer&gt;</code> to get high
 lighted code with line numbers using the given <code>&lt;lexer&gt;</code>. See
 <a href="http://www.apache.org/dev/cmsref.html#code-hilighter">http://www.apache.org/dev/cmsref.html#code-hilighter</a> for main info and
 <a href="http://pygments.org/docs/lexers/">http://pygments.org/docs/lexers/</a> for supported lexers</p>
 <h2 id="html-and-markdown">HTML and Markdown<a class="headerlink" href="#html-and-markdown" title="Permanent link">&para;</a></h2>
 <p>Markdown supports embedding HTML. But be aware that contents of HTML elements
 are not further handled by the Markdown converter. Thus it is not possible
 to embed Markdown syntax inside of HTML elements to have them converted.</p>
 <h2 id="manual-generation">Manual Generation<a class="headerlink" href="#manual-generation" title="Permanent link">&para;</a></h2>
 <p>When commiting changes to pages into SVN the pages are automatically
 generated in <a href="http://felix.staging.apache.org">the staging site</a>.</p>
 <div class="info">
 <p>To generate the site locally, you must have checked out the complete SVN to access the tools:</p>

 <div class="codehilite"><pre><span class="nv">$ </span>svn <span class="s2">https://svn.apache.org/repos/asf/felix/site/ felix-site</span>
 </pre></div>
 </div>

 <p>To manually generate the site or single pages the <a href="http://svn.apache.org/repos/asf/felix/site">site</a>
 can be checked out from SVN. In addition Perl and Python must be installed
 for the build tools to work.</p>
 <p>To prepare for site build, the Markdown daemon has to be started:</p>
 <div class="codehilite"><pre><span class="nv">$ </span><span class="nb">export </span><span class="nv">MARKDOWN_SOCKET</span><span class="o">=</span><span class="s2">&quot;$PWD/tools/build/../markdown.socket&quot;</span>
 <span class="nv">$ </span><span class="nb">export </span><span class="nv">PYTHONPATH</span><span class="o">=</span><span class="s2">&quot;$PWD/tools/build&quot;</span>
 <span class="nv">$ </span>python <span class="s2">&quot;$PWD/tools/build/markdownd.py&quot;</span>
 </pre></div>


 <p>The <code>MARKDOWN_SOCKET</code> environment variables is also required by the <code>build_site.pl</code>
 and <code>build_file.pl</code> scripts to connect to the Markdown daemon.</p>
 <p>To build the complete site use the <code>build_site.pl</code> script:</p>
 <div class="codehilite"><pre><span class="nv">$ </span>tools/build/build_site.pl --source-base <span class="nv">$PWD</span>/trunk <span class="se">\</span>
     --target-base <span class="nv">$PWD</span>/trunk/target
 </pre></div>


 <p>To build a single page use the <code>build_file.pl</code> script:</p>
 <div class="codehilite"><pre><span class="nv">$ </span>tools/build/build_site.pl --source-base <span class="nv">$PWD</span>/trunk <span class="se">\</span>
     --target-base <span class="nv">$PWD</span>/trunk/target <span class="se">\</span>
     --source content/documentation.mdtext
 </pre></div>


 <p>The argument to the <code>--source</code> parameter is relative to the <code>--source-base</code> folder.</p>
 <h2 id="configuring-site-generation-on-mac">Configuring site generation on Mac<a class="headerlink" href="#configuring-site-generation-on-mac" title="Permanent link">&para;</a></h2>
 <div class="info">
 Those instructions were computed on Mountain Lion.
 </div>

 <p>A couple of Python and Perl libraries are required and need to be installed</p>
 <div class="codehilite"><pre><span class="nv">$ </span>sudo easy_install Pygments
 <span class="nv">$ </span>sudo easy_install Markdown
 </pre></div>


 <p>And for the Perl modules:</p>
 <div class="codehilite"><pre><span class="nv">$ </span>sudo cpan install XML::Atom::Feed
 <span class="nv">$ </span>sudo cpan install XML::RSS::Parser
 <span class="nv">$ </span>sudo cpan install XML::Parser::Lite
 <span class="nv">$ </span>sudo cpan install XML::RSS::Parser::Lite
 <span class="nv">$ </span>sudo cpan install Net::Twitter
 <span class="nv">$ </span>sudo cpan install SVN::Client
 </pre></div>


 <p>Be careful that some of those commands require time... Once done, launch the mardown daemon with the following command from the SVN root:</p>
 <div class="codehilite"><pre><span class="nv">$ </span><span class="nb">export </span><span class="nv">MARKDOWN_SOCKET</span><span class="o">=</span><span class="s2">&quot;$PWD/tools/build/../markdown.socket&quot;</span>
 <span class="nv">$ </span><span class="nb">export </span><span class="nv">PYTHONPATH</span><span class="o">=</span><span class="s2">&quot;$PWD/tools/build&quot;</span>
 <span class="nv">$ </span>python <span class="s2">&quot;$PWD/tools/build/markdownd.py&quot;</span>
 </pre></div>


 <p>And finally, generate the web site from the svn root with:</p>
 <div class="codehilite"><pre>tools/build/build_site.pl --source-base <span class="nv">$PWD</span>/trunk     --target-base <span class="nv">$PWD</span>/trunk/target
 </pre></div>
       <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
         Rev. 1874797 by pauls on Wed, 4 Mar 2020 14:01:05 +0000
       </div>
       <div class="trademarkFooter">
         Apache Felix, Felix, Apache, the Apache feather logo, and the Apache Felix project
         logo are trademarks of The Apache Software Foundation. All other marks mentioned
         may be trademarks or registered trademarks of their respective owners.
       </div>
     </div>
   </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
	<html>
	<!--

	Licensed to the Apache Software Foundation (ASF) under one or more
	contributor license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright ownership.
	The ASF licenses this file to You under the Apache License, Version 2.0
	(the "License"); you may not use this file except in compliance with
	the License. You may obtain a copy of the License at

	https://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	-->
	<head>
	<title>Apache Felix - Site How To</title>
	<link rel="icon" href="/res/favicon.ico">
	<link rel="stylesheet" href="/res/site.css" type="text/css" media="all">
	<link rel="stylesheet" href="/res/codehilite.css" type="text/css" media="all">
	<meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
	</head>
	<body>
	<div class="title">
	<div class="logo">
	<a href="https://felix.apache.org/">
	<img border="0" alt="Apache Felix" src="/res/logo.png">
	</a>
	</div>
	<div class="header">
	<a href="https://www.apache.org/">
	<img border="0" alt="Apache" src="/res/apache.png">
	</a>
	</div>
	</div>

	<div class="menu">
	<style type="text/css">
	/* The following code is added by mdx_elementid.py
	It was originally lifted from http://subversion.apache.org/style/site.css */
	/*
	* Hide class="elementid-permalink", except when an enclosing heading
	* has the :hover property.
	*/
	.headerlink, .elementid-permalink {
	visibility: hidden;
	}
	h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
	<p><a href="/news.html">News</a> <br />
	<a href="/license.html">License</a> <br />
	<a href="/downloads.cgi">Downloads</a> <br />
	<a href="/documentation.html">Documentation</a> <br />
	<a href="/documentation/community/project-info.html">Project Info</a> <br />
	<a href="/documentation/community/contributing.html">Contributing</a> <br />
	<a href="/sitemap.html">Site Map</a> <br />
	<a href="https://www.apache.org/">ASF</a> <br />
	<a href="https://www.apache.org/security/">Security</a> <br />
	<a href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a> <br />
	<a href="https://www.apache.org/foundation/thanks.html">Sponsors</a> </p>
	<iframe
	src="https://www.apache.org/ads/button.html"
	style="border-width:0; float: left"
	frameborder="0"
	scrolling="no"
	width="135"
	height="135">
	</iframe>
	</div>

	<div class="main">
	<div class="breadcrump" style="font-size: 80%;">
	<a href="/">Home</a> &raquo <a href="/documentation.html">Documentation</a> &raquo <a href="/documentation/development.html">Development</a>
	</div>

	<h1>Site How To</h1>
	<style type="text/css">
	/* The following code is added by mdx_elementid.py
	It was originally lifted from http://subversion.apache.org/style/site.css */
	/*
	* Hide class="elementid-permalink", except when an enclosing heading
	* has the :hover property.
	*/
	.headerlink, .elementid-permalink {
	visibility: hidden;
	}
	h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
	<p>The site is managed with the <a href="https://www.apache.org/dev/cms.html">Apache CMS</a>
	where the source is kept in SVN at <a href="https://svn.apache.org/repos/asf/felix/site/trunk/content">https://svn.apache.org/repos/asf/felix/site/trunk/content</a>.</p>
	<h2 id="to-update-the-documentation-using-the-cms-system">To update the documentation using the CMS system<a class="headerlink" href="#to-update-the-documentation-using-the-cms-system" title="Permanent link">¶</a></h2>
	<ul>
	<li>Install the bookmarklet from the <a href="https://cms.apache.org/">cms</a> page. You only have to do this once.</li>
	<li>Navigate to the page you wish to edit (on the live site, not in the cms).</li>
	<li>Click the bookmarklet. There will be a short pause while the CMS system is initialised for you.</li>
	<li>Click on <code>Edit</code> (to skip this step hack the bookmarklet to add an 'action=edit' param to the query string)</li>
	<li>The page editor should then be displayed.</li>
	<li>Click <code>Submit</code> to save your edit to the workarea</li>
	<li>Click <code>Commit</code> to save the updated file to SVN and trigger a staged build. (to skip this step click on the "Quick Commit" checkbox in the <code>Edit</code> form).</li>
	<li>The results should appear shortly on the <a href="http://felix.staging.apache.org/content/documentation.html">staging</a> site. (You may have to force the page to refresh in order to see the updated content)</li>
	<li>Once you are happy with the updated page, click on <code>Publish Site</code> to deploy.</li>
	</ul>
	<p>There is also a <a href="https://www.apache.org/dev/cmsref.html">Reference Manual</a> of the Apache CMS as well as a
	video tutorial at <a href="http://s.apache.org/cms-tutorial">http://s.apache.org/cms-tutorial</a>.</p>
	<h2 id="features-of-the-apache-felix-site">Features of the Apache Felix Site<a class="headerlink" href="#features-of-the-apache-felix-site" title="Permanent link">¶</a></h2>
	<p>This section lists some Apache Felix features to help with the maintenance
	of the site, such as automatic link generation.</p>
	<p>Start the file with a <code>Title:</code> line to define the page title and the first H1 tag:</p>
	<div class="codehilite"><pre><span class="n">Title</span><span class="o">:</span> <span class="n">Page</span> <span class="n">Title</span>

	<span class="n">Here</span> <span class="n">comes</span> <span class="n">the</span> <span class="n">content</span> <span class="n">separated</span> <span class="k">with</span> <span class="n">a</span> <span class="n">blank</span> <span class="n">like</span> <span class="n">from</span> <span class="n">the</span>
	<span class="n">header</span> <span class="o">...</span>
	</pre></div>


	<p>The last modification information from SVN (revision, committer, and
	date/time) is automatically added when the page is rendered</p>
	<p>Excerpts can be added to a page using the <code>Excerpt:</code> header:</p>
	<div class="codehilite"><pre><span class="n">Title</span><span class="o">:</span> <span class="n">Page</span> <span class="n">Title</span>
	<span class="n">Excerpt</span><span class="o">:</span> <span class="n">Summary</span> <span class="n">of</span> <span class="n">the</span> <span class="n">page</span> <span class="k">for</span> <span class="n">inclusion</span> <span class="k">in</span> <span class="n">other</span> <span class="n">pages</span><span class="o">;</span>
	<span class="n">continuation</span> <span class="n">of</span> <span class="n">the</span> <span class="n">excerpt</span> <span class="n">must</span> <span class="n">be</span> <span class="n">indented</span>

	<span class="n">Here</span> <span class="n">comes</span> <span class="n">the</span> <span class="n">content</span> <span class="n">separated</span> <span class="k">with</span> <span class="n">a</span> <span class="n">blank</span> <span class="n">like</span> <span class="n">from</span> <span class="n">the</span>
	<span class="n">header</span> <span class="o">...</span>
	</pre></div>


	<p>Metadata from child pages can be referred to in the content with the
	Django variable reference notation using the child page name (without
	extension) as its container; e.g. for the child page named <code>childpage</code>:</p>
	<div class="codehilite"><pre><span class="cp">{{</span> <span class="nv">children.childpage.headers.excerpt</span> <span class="cp">}}</span><span class="x"></span>
	<span class="cp">{{</span> <span class="nv">children.childpage.headers.title</span> <span class="cp">}}</span><span class="x"></span>
	</pre></div>


	<p>Content Pages can contain Django templates of the form <code>{{...}}</code> and <code>{%...%}</code>.
	If so, the page content is evaluated as a Django template before running
	it through the page template.</p>
	<p>Any page in the site can be referenced with refs.pagename returning properties:</p>
	<dl>
	<dt><code>.path</code></dt>
	<dd>the absolute path of the page on the site</dd>
	<dt><code>.headers</code></dt>
	<dd>page headers (e.g. <code>.title</code>, <code>.excerpt</code>)</dd>
	<dt><code>.content</code></dt>
	<dd>the raw page content</dd>
	</dl>
	<p>All pages in the children namespace are also available in the refs namespace</p>
	<p>Some usefull hints:</p>
	<p>Printing title of another page "handler":</p>
	<div class="codehilite"><pre><span class="x"> :::django</span>
	<span class="x"> </span><span class="cp">{{</span> <span class="nv">refs.handler.headers.title</span> <span class="cp">}}</span><span class="x"></span>
	</pre></div>


	<p>Printing excerpt of another page "handler":</p>
	<div class="codehilite"><pre><span class="x"> :::django</span>
	<span class="x"> </span><span class="cp">{{</span> <span class="nv">refs.handler.headers.excerpt</span> <span class="cp">}}</span><span class="x"></span>
	</pre></div>


	<p>Linking to another page "handler":</p>
	<div class="codehilite"><pre><span class="x"> :::django</span>
	<span class="x"> (</span><span class="cp">{{</span> <span class="nv">refs.handler.path</span> <span class="cp">}}</span><span class="x">)</span>
	</pre></div>


	<p>Printing title as a link to another page "handler":</p>
	<div class="codehilite"><pre><span class="x"> :::django</span>
	<span class="x"> [</span><span class="cp">{{</span> <span class="nv">refs.handler.headers.title</span> <span class="cp">}}</span><span class="x">](</span><span class="cp">{{</span> <span class="nv">refs.handler.path</span> <span class="cp">}}</span><span class="x">)</span>
	</pre></div>


	<p>Printing excerpt as a link to another page "handler":</p>
	<div class="codehilite"><pre><span class="x"> :::django</span>
	<span class="x"> [</span><span class="cp">{{</span> <span class="nv">refs.handler.headers.excerpt</span> <span class="cp">}}</span><span class="x">](</span><span class="cp">{{</span> <span class="nv">refs.handler.path</span> <span class="cp">}}</span><span class="x">)</span>
	</pre></div>


	<p>Print a bullet pointed child page list:</p>
	<div class="codehilite"><pre><span class="x"> :::django</span>
	<span class="x"> </span><span class="cp">{%</span> <span class="k">for</span> <span class="nv">label</span><span class="o">,</span> <span class="nv">page</span> <span class="k">in</span> <span class="nv">children</span> <span class="cp">%}</span><span class="x">* [</span><span class="cp">{{</span> <span class="nv">page.headers.title</span> <span class="cp">}}</span><span class="x">](</span><span class="cp">{{</span> <span class="nv">page.path</span> <span class="cp">}}</span><span class="x">)</span>
	<span class="x"> </span><span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span><span class="x"></span>
	</pre></div>


	<div class="note">
	It is important to have the first part as a single line, otherwise
	the Django/Markdown combo will create a list for each entry.
	</div>

	<h2 id="code-highlighting">Code Highlighting<a class="headerlink" href="#code-highlighting" title="Permanent link">¶</a></h2>
	<p>Code Highlighting works by indenting code by four blanks. To indicate the
	type of highlighting preced the code style text with either <code>:::<lexer></code> to
	get high lighted code using the given <code><lexer></code> or <code>#!<lexer></code> to get high
	lighted code with line numbers using the given <code><lexer></code>. See
	<a href="http://www.apache.org/dev/cmsref.html#code-hilighter">http://www.apache.org/dev/cmsref.html#code-hilighter</a> for main info and
	<a href="http://pygments.org/docs/lexers/">http://pygments.org/docs/lexers/</a> for supported lexers</p>
	<h2 id="html-and-markdown">HTML and Markdown<a class="headerlink" href="#html-and-markdown" title="Permanent link">¶</a></h2>
	<p>Markdown supports embedding HTML. But be aware that contents of HTML elements
	are not further handled by the Markdown converter. Thus it is not possible
	to embed Markdown syntax inside of HTML elements to have them converted.</p>
	<h2 id="manual-generation">Manual Generation<a class="headerlink" href="#manual-generation" title="Permanent link">¶</a></h2>
	<p>When commiting changes to pages into SVN the pages are automatically
	generated in <a href="http://felix.staging.apache.org">the staging site</a>.</p>
	<div class="info">
	<p>To generate the site locally, you must have checked out the complete SVN to access the tools:</p>

	<div class="codehilite"><pre><span class="nv">$ </span>svn <span class="s2">https://svn.apache.org/repos/asf/felix/site/ felix-site</span>
	</pre></div>
	</div>

	<p>To manually generate the site or single pages the <a href="http://svn.apache.org/repos/asf/felix/site">site</a>
	can be checked out from SVN. In addition Perl and Python must be installed
	for the build tools to work.</p>
	<p>To prepare for site build, the Markdown daemon has to be started:</p>
	<div class="codehilite"><pre><span class="nv">$ </span><span class="nb">export </span><span class="nv">MARKDOWN_SOCKET</span><span class="o">=</span><span class="s2">"$PWD/tools/build/../markdown.socket"</span>
	<span class="nv">$ </span><span class="nb">export </span><span class="nv">PYTHONPATH</span><span class="o">=</span><span class="s2">"$PWD/tools/build"</span>
	<span class="nv">$ </span>python <span class="s2">"$PWD/tools/build/markdownd.py"</span>
	</pre></div>


	<p>The <code>MARKDOWN_SOCKET</code> environment variables is also required by the <code>build_site.pl</code>
	and <code>build_file.pl</code> scripts to connect to the Markdown daemon.</p>
	<p>To build the complete site use the <code>build_site.pl</code> script:</p>
	<div class="codehilite"><pre><span class="nv">$ </span>tools/build/build_site.pl --source-base <span class="nv">$PWD</span>/trunk <span class="se">\</span>
	--target-base <span class="nv">$PWD</span>/trunk/target
	</pre></div>


	<p>To build a single page use the <code>build_file.pl</code> script:</p>
	<div class="codehilite"><pre><span class="nv">$ </span>tools/build/build_site.pl --source-base <span class="nv">$PWD</span>/trunk <span class="se">\</span>
	--target-base <span class="nv">$PWD</span>/trunk/target <span class="se">\</span>
	--source content/documentation.mdtext
	</pre></div>


	<p>The argument to the <code>--source</code> parameter is relative to the <code>--source-base</code> folder.</p>
	<h2 id="configuring-site-generation-on-mac">Configuring site generation on Mac<a class="headerlink" href="#configuring-site-generation-on-mac" title="Permanent link">¶</a></h2>
	<div class="info">
	Those instructions were computed on Mountain Lion.
	</div>

	<p>A couple of Python and Perl libraries are required and need to be installed</p>
	<div class="codehilite"><pre><span class="nv">$ </span>sudo easy_install Pygments
	<span class="nv">$ </span>sudo easy_install Markdown
	</pre></div>


	<p>And for the Perl modules:</p>
	<div class="codehilite"><pre><span class="nv">$ </span>sudo cpan install XML::Atom::Feed
	<span class="nv">$ </span>sudo cpan install XML::RSS::Parser
	<span class="nv">$ </span>sudo cpan install XML::Parser::Lite
	<span class="nv">$ </span>sudo cpan install XML::RSS::Parser::Lite
	<span class="nv">$ </span>sudo cpan install Net::Twitter
	<span class="nv">$ </span>sudo cpan install SVN::Client
	</pre></div>


	<p>Be careful that some of those commands require time... Once done, launch the mardown daemon with the following command from the SVN root:</p>
	<div class="codehilite"><pre><span class="nv">$ </span><span class="nb">export </span><span class="nv">MARKDOWN_SOCKET</span><span class="o">=</span><span class="s2">"$PWD/tools/build/../markdown.socket"</span>
	<span class="nv">$ </span><span class="nb">export </span><span class="nv">PYTHONPATH</span><span class="o">=</span><span class="s2">"$PWD/tools/build"</span>
	<span class="nv">$ </span>python <span class="s2">"$PWD/tools/build/markdownd.py"</span>
	</pre></div>


	<p>And finally, generate the web site from the svn root with:</p>
	<div class="codehilite"><pre>tools/build/build_site.pl --source-base <span class="nv">$PWD</span>/trunk --target-base <span class="nv">$PWD</span>/trunk/target
	</pre></div>
	<div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
	Rev. 1874797 by pauls on Wed, 4 Mar 2020 14:01:05 +0000
	</div>
	<div class="trademarkFooter">
	Apache Felix, Felix, Apache, the Apache feather logo, and the Apache Felix project
	logo are trademarks of The Apache Software Foundation. All other marks mentioned
	may be trademarks or registered trademarks of their respective owners.
	</div>
	</div>
	</body>
	</html>