[
https://issues.apache.org/jira/browse/DOXIA-617?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17649206#comment-17649206
]
Bertrand Martin commented on DOXIA-617:
---------------------------------------
Yes, headers are currently supported. They are added to the {{<head>}} section
of the produced HTML as a {{<meta name="header name" content="header value">}}.
One header item is processed differently though: {{title}} which is rendered
with the {{<title>}} tag.
Example:
{code:markdown}
title: An Example of a Markdown File
description: Example of a Markdown file properly processed with a mix of Doxia,
Flexmark and Maven Site Plugin
keywords: markdown,flexmark,maven,doxia,site,header
## My heading
Some content
{code}
This will be rendered as:
{code:html}
<html>
<head>
<title>An Example of a Markdown File</title>
<meta name="description" content="Example of a Markdown file properly
processed with a mix of Doxia, Flexmark and Maven Site Plugin">
<meta name="keywords" content="markdown,flexmark,maven,doxia,site,header">
</head>
<body>
<h2>My heading</h2>
<p>Some content</p>
</body>
</html>
{code}
Note that with the YAML Front Matter extension, the new syntax for specifying
headers will become:
{code:markdown}
title: An Example of a Markdown File
description: Example of a Markdown file properly processed with a mix of Doxia,
Flexmark and Maven Site Plugin
keywords: markdown,flexmark,maven,doxia,site,header
---
## My heading
Some content
{code}
Ideally, both syntaxes would be allowed, as some projects do use Markdown
headers with Doxia (all of my company's documentation is written this way!).
It would be done by "simply" inserting the {{---}} mark where it's supposed to
be... if it's not already present.
I trust you'll make this happen! 😊
> 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
>
> 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)
