Apache Forrest > Plugins
Plugin: Markdown output
 
Font size:      

Welcome to the org.apache.forrest.plugin.output.Markdown Plugin

Overview

Produce output in Markdown "mdtext" format. This enables use of Forrest as a tool for gathering input from various sources, and generate a consistent set of output documents. See example.

Howto

In your project's forrest.properties file make the following changes ...

  • Declare the org.apache.forrest.plugin.output.Markdown plugin at the project.required.plugins property (comma-separated list).
  • Uncomment the project.start-uri property and set it to be markdown-start.xml

Now do 'forrest' to build your site as normal.

Alongside each *.html file there will now be a matching *.mdtext file.

Of course you can also do 'forrest run' and request individual *.mdtext files.

Notes

This first version of the plugin might not convert all complex content.

May need a combination of editing output, editing input and running again, or tweaking transformations to do special things.

See the two transformations mentioned below. We can adjust to treat certain input differently.

The initial anakia-to-markdown.xsl referred to below was from https://svn.apache.org/repos/infra/infrastructure/trunk/projects/cms/prototype/conversion-utilities/anakia2markdown.xslt (r776923 2010-09-24). Monitor/integrate changes.

See some other notes here: https://svn.apache.org/repos/infra/infrastructure/trunk/projects/cms/prototype/Markdown-limitations.mdtext

See some notes in this mail thread on the "site-dev" mail list: "[CMS] handling tables and other complex html" 2010-10-16.

How it works

Explanation of how this plugin works and how its output can be enhanced with additional processing.

Without touching any of the site source content or navigation system, we need to additionally inject another set of links to be processed. Each html output document will then also have a matching URI with *.mdtext extension.

This is achieved with the input.xmap sitemap. For the requested markdown-start.xml pipeline, Forrest will generate the "linkmap" of the complete site navigation, then apply a transformation to amend each link.

This automatically enables the crawler to gather this set of links.

The output.xmap sitemap then handles each mdtext URI to transform the internal XML content structure. This plugin provides a stylesheet document-to-anakia.xsl to transform the internal XML to something close to Anakia-like XML The following transformation anakia-to-markdown.xsl (see above) transforms that XML to Markdown text.

To enhance the output, either amend the document-to-anakia.xsl stylesheet or the anakia-to-markdown.xsl stylesheet (and please send changes), or insert another output transformation.

Links