[DOXIA-617] doxia-module-markdown: Add support for --- header section marks

• Type: Improvement
• Status: Closed
• Priority: Major
• Resolution: Fixed
• Fix Version/s: 1.12.0, 2.0.0-M5, 2.0.0
• Component/s: Module - Markdown
• Assignee: Herve Boutemy
• Reporter: Bertrand Martin
• Created: 04/Jan/21 11:43
• Updated: 14/Dec/23 16:47
• Resolved: 04/Jan/23 17:14

Description

Use Case

It is "generally" accepted that document header metadata in Markdown (like title, author, etc.) must be specified inside a header section, delimited with 3 hypens:

---
title: My Doc Title
author: Myself
keywords: great,doc
---
# Introduction
...

See:

• https://bookdown.org/yihui/rmarkdown/html-document.html
• https://pandoc.org/MANUAL.html#extension-yaml_metadata_block
• https://github.com/vsch/flexmark-java/wiki/Extensions#yaml-front-matter

Currently, the only supported syntax for document header metadata is the very same as above, but without the 3 hypens marking the header section:

title: My Doc Title
author: Myself
keywords: great,doc

# Introduction
...

Specification

Enable the YAML Front Matter Extension of Flexmark so that such header is processed automatically (nothing to code here!)

Keep the default behavior (we want backward compatibility) with the parsing of metadatas (which won't be affected by the YAML Front Matter parsing).

Doc

Update the documentation on how to use Markdown in Doxia. This feature (document metadata) is currently not documented.

We should have a small guide on how to use Markdown in Doxia, and its specific features (metadatas, macros, etc.)

Test

Add corresponding unit tests and integration tests (for both old and new syntaxes)

Issue Links

• links to: GitHub Pull Request #132