[HADOOP-9432] Add support for markdown .md files in site documentation

• Type: New Feature
• Status: Closed
• Priority: Minor
• Resolution: Fixed
• Affects Version/s: 3.0.0-alpha1
• Fix Version/s: 2.3.0
• Component/s: build, documentation
• Assignee: Steve Loughran
• Reporter: Steve Loughran
• Created: 25/Mar/13 14:15
• Updated: 12/May/16 18:22
• Resolved: 11/Jul/13 16:05

Description

The "markdown" syntax for marking up text is something which the mvn site build can be set up to support alongside the existing APT formatted text.

Markdown offers many advantages

1. It's more widely understood.
2. There's tooling support in various text editors (TextMate, an IDEA plugin and others)
3. It can be directly rendered in github
4. the .md files can be named .md.vm to trigger velocity preprocessing, at the expense of direct viewing in github

feature #3 is good as it means that you can point people directly at a doc via a github mirror, and have it rendered.

I propose adding the options to Maven to enable content be written as .md and .md.vm files in the directory src/site/markdown. This does not require any changes to the existing .apt files, which can co-exist and cross-reference each other.

Issue Links

• is depended upon by: HADOOP-9361 Strictly define the expected behavior of filesystem APIs and write tests to verify compliance