[
https://issues.apache.org/jira/browse/DOXIA-617?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17652837#comment-17652837
]
ASF GitHub Bot commented on DOXIA-617:
--------------------------------------
bertysentry commented on PR #132:
URL: https://github.com/apache/maven-doxia/pull/132#issuecomment-1367308292
@hboutemy Thank you for taking care of this!
While "it works"(tm) as per the tests, the original intent was to remove as
much as possible specific code to handle these headers and use the YAML Front
Matter extension of Flexmark, which can handle complex data, like arrays, etc.
You're right that even if we use Flexmark's extension, we still have to
handle the `title` metadata specifically, but it's really simple:
1. If `title:` is specified in metadata, use it as `<title>` and remove it
from `<meta name="title"...>`
2. If `title:` is not specified, search for the first heading in the document
My opinion is still that using Flexmark is better in the long run, avoiding
specific parsing (like handling empty lines or not, etc.)
> doxia-module-markdown: Add support for --- header section marks
> ---------------------------------------------------------------
>
> Key: DOXIA-617
> URL: https://issues.apache.org/jira/browse/DOXIA-617
> Project: Maven Doxia
> Issue Type: Improvement
> Components: Module - Markdown
> Reporter: Bertrand Martin
> Priority: Major
> Fix For: 1.12.0, 2.0.0-M5
>
>
> h1. 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:
> {noformat}
> ---
> title: My Doc Title
> author: Myself
> keywords: great,doc
> ---
> # Introduction
> ...
> {noformat}
> 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:
> {noformat}
> title: My Doc Title
> author: Myself
> keywords: great,doc
> # Introduction
> ...
> {noformat}
> h1. 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).
> h1. 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.)
> h1. Test
> Add corresponding unit tests and integration tests (for both old and new
> syntaxes)
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
