Extract and re-write "front matter" in markdown documents

It's increasingly common for YAML to be used as metadata in front of
markdown documents. md4c does not handle this, so we need to remove
it ahead of time, lest md4c misinterpret it as heading text or so.

The --- fences are expected to be consistent regardless of the format of
what's between them, and the yaml (or whatever) parser does not need to
see them. So we remove them while reading, and QTextMarkdownWriter
writes them around the front matter if there is any.

If your application needs to parse this "front matter", just call
qtd->metaInformation(QTextDocument::FrontMatter).toUtf8() and feed that
to some parser that you've linked in, such as yaml-cpp.

Since YAML is used with GitHub Docs, we consider this feature to be part
of the GitHub dialect:
https://docs.github.com/en/contributing/writing-for-github-docs/using-yaml-frontmatter

[ChangeLog][QtGui][Text] Markdown "front matter" (usually YAML) is now
extracted during parsing (GitHub dialect) and can be retrieved from
QTextDocument::metaInformation(FrontMatter). QTextMarkdownWriter also
writes front matter (if any) to the output.

Fixes: QTBUG-120722
Change-Id: I220ddcd2b94c99453853643516ca7a36bb2bcd6f
Reviewed-by: Axel Spoerl <axel.spoerl@qt.io>

1 files changed, 13 insertions, 0 deletions

diff --git a/src/gui/text/qtextmarkdownwriter.cpp b/src/gui/text/qtextmarkdownwriter.cpp
index 5fb67ccc67..c8a5d40b52 100644
--- a/src/gui/text/qtextmarkdownwriter.cpp
+++ b/src/gui/text/qtextmarkdownwriter.cpp
@@ -10,6 +10,7 @@
 #include "qtexttable.h"
 #include "qtextcursor.h"
 #include "qtextimagehandler_p.h"
+#include "qtextmarkdownimporter_p.h"
 #include "qloggingcategory.h"
 #if QT_CONFIG(itemmodel)
 #include "qabstractitemmodel.h"
@@ -38,6 +39,7 @@ QTextMarkdownWriter::QTextMarkdownWriter(QTextStream &stream, QTextDocument::Mar
 
 bool QTextMarkdownWriter::writeAll(const QTextDocument *document)
 {
+    writeFrontMatter(document->metaInformation(QTextDocument::FrontMatter));
     writeFrame(document->rootFrame());
     return true;
 }
@@ -76,6 +78,17 @@ void QTextMarkdownWriter::writeTable(const QAbstractItemModel *table)
 }
 #endif
 
+void QTextMarkdownWriter::writeFrontMatter(const QString &fm)
+{
+    if (fm.isEmpty() || !m_features.testFlag(static_cast<QTextDocument::MarkdownFeature>(
+                QTextMarkdownImporter::FeatureFrontMatter)))
+        return;
+    m_stream << "---\n"_L1 << fm;
+    if (!fm.endsWith(qtmw_Newline))
+        m_stream << qtmw_Newline;
+    m_stream << "---\n"_L1;
+}
+
 void QTextMarkdownWriter::writeFrame(const QTextFrame *frame)
 {
     Q_ASSERT(frame);