Qtの基礎 - Markdown

概要

Markdownは、軽量のマークアップ言語であり、テキストを簡単にフォーマットするために使用される。
主にWebで使用されており、HTMLに変換することができるが、Markdown自体は視覚的にわかりやすく、読みやすいテキストを提供する。
そのため、ブログ、ドキュメント、READMEファイル等、様々な場面で広く利用されている。

Markdownファイルは拡張子として、.md または .markdown が使用されることが一般的である。

Markdownの基本的な構文はシンプルであり、見出しを作成するためにはテキストの前にシャープ記号を使用する。
例えば、シャープ記号1つで大見出し、2つで中見出し、3つで小見出しといった具合に階層を指定できる。

強調する部分を表現するためには、テキストをアスタリスクやアンダースコアで囲むことにより、太字や斜体などを簡単に表現することができる。

リンクを作成する場合は、表示するテキストを角括弧で囲み、その直後にリンク先URLを丸括弧で記述する。
これにより、簡単にハイパーリンクを生成できる。

また、画像を挿入する場合も同様の構文を使用するが、リンクテキストの前に感嘆符を追加する。

コードスニペットを記述する場合、インラインコードはバッククォートで囲み、複数行のコードブロックは3つのバッククォートで囲む。
これにより、コードが視覚的に区別され、読みやすくなる。

Markdownはシンプルでありながら、基本的な文章構造を維持しつつ、HTMLのような複雑なタグを使用することなくテキストにフォーマットを適用できるため、
多くのユーザに使用されている。

Markdownファイルの読み込み

以下の例では、指定されたMarkdownファイルを読み込んでいる。

 #include <QCoreApplication>
 #include <QFile>
 #include <QTextStream>
 #include <QDebug>
 
 QString readMarkdownFile(const QString& filePath)
 {
    QFile file(filePath);
    if (!file.open(QIODevice::ReadOnly | QIODevice::Text)) {
       qDebug() << "ファイルを開けませんでした:" << filePath;
       return QString();
    }
    QTextStream in(&file);
 
    return in.readAll();
 }
 
 int main(int argc, char *argv[])
 {
    QCoreApplication a(argc, argv);
 
    QString filePath = "input.md";
    QString content = readMarkdownFile(filePath);
 
    if (!content.isEmpty()) {
       qDebug() << "ファイルの内容:";
       qDebug().noquote() << content;
    }
    else {
       qDebug() << "ファイルの読み込みに失敗しました。";
    }
 
    return a.exec();
 }

Markdownファイルの書き込み

以下の例では、指定されたコンテンツをMarkdownファイルを書き込んでいる。

 #include <QCoreApplication>
 #include <QFile>
 #include <QTextStream>
 #include <QDebug>
 
 bool writeMarkdownFile(const QString& filePath, const QString& content)
 {
    QFile file(filePath);
    if (!file.open(QIODevice::WriteOnly | QIODevice::Text)) {
       qDebug() << "ファイルを書き込みエラー: " << filePath;
       return false;
    }
    QTextStream out(&file);
    out << content;
 
    return true;
 }
 
 int main(int argc, char *argv[])
 {
    QCoreApplication a(argc, argv);
 
    QString filePath = "output.md";
    QString content = "# サンプルマークダウン\n\nこれはテストです。\n";
 
    if (writeMarkdownFile(filePath, content)) {
       qDebug() << "ファイルの書き込みに成功";
    }
    else {
       qDebug() << "ファイルの書き込みに失敗";
    }
 
    return a.exec();
 }

Markdownファイルの操作

以下の例では、指定されたコンテンツに対して様々な操作 (ヘッダの追加、ボールドテキストの追加、リンクの追加、ヘッダの抽出) を行っている。

 #include <QCoreApplication>
 #include <QDebug>
 
 QString addHeader(const QString& content, int level, const QString& headerText)
 {
    QString header = QString("#").repeated(level) + " " + headerText + "\n\n";
    return header + content;
 }
 
 QString addBoldText(const QString& content, const QString& text)
 {
    return content + "**" + text + "**\n";
 }
 
 QString addLink(const QString& content, const QString& text, const QString& url)
 {
    return content + "[" + text + "](" + url + ")\n";
 }
 
 QStringList extractHeaders(const QString& content)
 {
    QStringList headers;
    QStringList lines = content.split("\n");
 
    for (const QString& line : lines) {
       if (line.startsWith("#")) {
          headers << line.trimmed();
       }
    }
 
    return headers;
 }
 
 int main(int argc, char *argv[])
 {
    QCoreApplication a(argc, argv);
 
    QString content = "# 元のヘッダ\n\n元のコンテンツ\n";
 
    // ヘッダの追加
    content = addHeader(content, 2, "新しいサブヘッダ");
    qDebug() << "ヘッダー追加後:";
    qDebug().noquote() << content;
 
    // ボールドテキストの追加
    content = addBoldText(content, "重要な情報");
    qDebug() << "ボールドテキスト追加後:";
    qDebug().noquote() << content;
 
    // リンクの追加
    content = addLink(content, "QtのWebサイト", "https://www.qt.io/");
    qDebug() << "リンク追加後:";
    qDebug().noquote() << content;
 
    // ヘッダの抽出
    QStringList headers = extractHeaders(content);
    qDebug() << "抽出されたヘッダー:";
    for (const QString& header : headers) {
       qDebug().noquote() << header;
    }
 
    return a.exec();
 }

cmarkライブラリ

cmarkライブラリとは

cmarkライブラリは、CommonMarkのC言語リファレンス実装で、Markdown構文の合理化バージョンである。

CommonMarkドキュメントを抽象構文木 (AST) にパースして、
ASTを操作、ドキュメントをHTML、groff man、LaTeX、CommonMark、ASTのXML表現にレンダリングする関数を備えたライブラリである。

また、CommonMark文書の解析とレンダリングのためのコマンドラインプログラム (cmark) も提供する。

ライブラリの機能と特徴を以下に示す。 下記の機能により、cmarkライブラリはMarkdownの解析や変換だけでなく、複雑なドキュメント処理システムの構築にも使用できる。

• マークダウンの解析

  cmarkは、Markdownテキストを構文解析し、抽象構文木 (AST) を生成する。

  CommonMark標準に準拠しており、仕様に基づいた確実な解析が可能である。

  
  

• MarkdownからHTMLへの変換

  解析されたMarkdownをHTMLに変換する。

  変換時に様々なオプションを指定することで出力をカスタマイズできる。

  
  

• AST (抽象構文木) の操作

  解析されたMarkdownのASTを直接操作できる。

  これにより、Markdownの構造を動的に変更したり、カスタム処理を行ったりすることが可能である。

  
  

• カスタム出力

  特定のニーズに合わせた出力フォーマットのカスタマイズが可能である。

  出力内容を制御するためのオプションやAPIが提供されている。

  
  

• マルチスレッドセーフ

  並行処理を行うアプリケーションでも安全に使用できる。

  
  

• 様々な出力形式

  HTML以外にも、LaTeX、XML、Manページ形式等、複数の出力形式をサポートしている。

  
  

• UTF-8サポート

  Unicode文字を適切に処理する。

  
  

• サニタイズ機能

  XSS攻撃を防ぐため、HTMLの安全な出力オプションを提供している。

  
  

• コマンドラインツール

  ライブラリと共にコマンドラインツールも提供されており、ファイルの変換やデバッグに使用できる。

cmarkライブラリのライセンス

cmarkライブラリは、2条項BSDライセンスに準拠している。

cmarkライブラリのインストール

パッケージ管理システムからインストール

# RHEL
sudo dnf install cmark

# SUSE
sudo zypper install cmark

ソースコードからインストール

cmarkライブラリのGithubにアクセスして、ソースコードをダウンロードする。
ダウンロードしたファイルを解凍する。

tar xf cmark-<バージョン>.tar.gz
cd cmark-<バージョン>

cmarkライブラリをビルドおよびインストールする。

mkdir build && cd build

cmake -DCMAKE_BUILD_TYPE=Release \
      -DCMAKE_INSTALL_PREFIX=<cmakeライブラリのインストールディレクトリ> \
      ..
make -j $(nproc)
make install

cmark-gfmライブラリ

cmark-gfmライブラリとは

cmark-gfmライブラリは、CommonMarkのC言語リファレンス実装の拡張版であり、GitHub Flavored Markdown (GFM) の解析と変換のためのライブラリである。
Webアプリケーション、デスクトップアプリケーション、コマンドラインツール等、様々な場面でMarkdownを扱う時に有用なライブラリである。

ライブラリの機能と特徴を以下に示す。 下記の機能により、cmark-gfmライブラリはMarkdownの解析や変換だけでなく、複雑なドキュメント処理システムの構築にも使用できる。

• マークダウンの解析

  Markdownテキストを構文解析して、抽象構文木 (AST) を生成する。

  標準的なMarkdown構文に加えて、GFM固有の拡張をサポートしている。

  
  

• MarkdownからHTMLへの変換

  解析されたMarkdownをHTMLに変換する。

  変換時に様々なオプションが指定できる。(例: 安全なHTML出力、ハードブレークの処理方法等)

  
  

• HTMLからマークダウンへの変換

  HTMLをMarkdownに変換する機能も提供している。

  
  

• AST (抽象構文木) の操作

  解析されたMarkdownのASTを直接操作できる。

  これにより、Markdownの構造を動的に変更したり、カスタム処理を行ったりすることが可能である。

  
  

• GitHub Flavored Markdown (GFM) の拡張機能サポート
  • テーブル
  • タスクリスト
  • 取り消し線
  • 自動リンク
  • コードブロックの言語指定

  
  

• カスタム拡張の実装

  ライブラリを拡張して、独自のMarkdown要素や処理を追加できる。

  
  

• マルチスレッドセーフ

  並行処理を行うアプリケーションでも安全に使用できる。

  
  

• 様々な出力形式

  HTML以外にも、XMLやManページ形式等、複数の出力形式をサポートしている。

  
  

• UTF-8サポート

  Unicode文字を適切に処理する。

  
  

• リンクの参照解決

  Markdown内のリンク参照を自動的に解決する。

  
  

• 脚注のサポート

  脚注の解析と適切な出力をサポートしている。

• サニタイズ機能

  XSS攻撃を防ぐため、HTMLの安全な出力オプションを提供している。

  
  

• エスケープ処理

  特殊文字の適切なエスケープ処理を行う。

  
  

• フェンスドコードブロックの処理

  コードブロックの言語指定や構文ハイライトの準備をする。

  
  

• コマンドラインツール

  ライブラリと共にコマンドラインツールも提供されており、ファイルの変換やデバッグに使用できる。

cmark-gfmライブラリのライセンス

cmark-gfmライブラリは、2条項BSDライセンスに準拠している。

cmark-gfmライブラリのインストール

cmark-gfmライブラリのGithubにアクセスして、ソースコードをダウンロードする。
ダウンロードしたファイルを解凍する。

tar xf cmark-gfm-<バージョン>.tar.gz
cd cmark-gfm-<バージョン>

cmark-gfmライブラリをビルドおよびインストールする。

mkdir build && cd build

cmake -DCMAKE_BUILD_TYPE=Release \
      -DCMAKE_INSTALL_PREFIX=<cmake-gfmライブラリのインストールディレクトリ> \
      ..
make -j $(nproc)
make install

HTMLファイルへ変換

以下の例では、cmark-gfmライブラリを使用して、MarkdownファイルからHTMLファイルへ変換している。

 #include <QCoreApplication>
 #include <QFile>
 #include <QTextStream>
 #include <cmark-gfm.h>
 #include <QDebug>
 
 QString readMarkdownFile(const QString& fileName)
 {
    QFile file(fileName);
    if (!file.open(QIODevice::ReadOnly | QIODevice::Text)) {
       qDebug() << "ファイルのオープンに失敗";
       return QString();
    }
 
    QTextStream in(&file);
    QString content = in.readAll();
    file.close();
 
    return content;
 }
 
 QString markdownToHtml(const QString& markdown)
 {
    QByteArray markdownUtf8 = markdown.toUtf8();
    char *htmlOutput = cmark_markdown_to_html(markdownUtf8.constData(), markdownUtf8.size(), CMARK_OPT_DEFAULT);
    QString html = QString::fromUtf8(htmlOutput);
 
    free(htmlOutput);
 
    return html;
 }
 
 int main()
 {
    QString fileName = "<Markdownファイルのパス>";
    QString markdownContent = readMarkdownFile(fileName);
 
    if (markdownContent.isEmpty()) {
       qDebug() << "ファイルが存在しない または 空";
       return -1;
    }
 
    qDebug() << "Original Markdown content:";
    qDebug() << markdownContent;
 
    QString htmlContent = markdownToHtml(markdownContent);
    qDebug() << "変換されたHTMLの内容:";
    qDebug() << htmlContent;
 
    return 0;
 }

HTMLファイルへ変換

以下の例では、cmark-gfmライブラリを使用して、HTMLファイルからMarkdownファイルへ変換している。

 #include <QCoreApplication>
 #include <QFile>
 #include <QTextStream>
 #include <cmark-gfm.h>
 #include <QDebug>
 
 bool writeMarkdownFile(const QString& fileName, const QString& content)
 {
    QFile file(fileName);
    if (!file.open(QIODevice::WriteOnly | QIODevice::Text)) {
       qDebug() << "ファイルのオープンに失敗";
       return false;
    }
 
    QTextStream out(&file);
    out << content;
    file.close();
 
    return true;
 }
 
 QString htmlToMarkdown(const QString& html)
 {
    QByteArray htmlUtf8 = html.toUtf8();
    cmark_node* doc = cmark_parse_document(htmlUtf8.constData(), htmlUtf8.size(), CMARK_OPT_DEFAULT);
    char* markdownOutput = cmark_render_commonmark(doc, CMARK_OPT_DEFAULT, 0);
    QString markdown = QString::fromUtf8(markdownOutput);
 
    free(markdownOutput);
    cmark_node_free(doc);
 
    return markdown;
 }
 
 int main()
 {
    QString fileName = "<HTMLファイルのパス>";
    QString htmlContent = "<h1>Hello, World!</h1><p>This is a <strong>bold</strong> text and <em>italic</em> text.</p>";
 
    QString markdownContent = htmlToMarkdown(htmlContent);
 
    qDebug() << "変換されたMarkdownの内容:";
    qDebug() << markdownContent;
 
    if (writeMarkdownFile(fileName, markdownContent)) {
       qDebug() << "Markdownファイルへの変換に成功";
    }
    else {
       qDebug() << "Markdownファイルへの変換に失敗";
       return -1;
    }
 
    return 0;
 }

その他のMarkdownパーサライブラリ

• Hoedown

  C言語で記述されたMarkdownパーサであり、パフォーマンスに優れたライブラリである。

• PEG Markdown Highlight

  PEGによるMarkdownパーサであり、Markdownの解析とシンタックスハイライトに特化している。

• Discount

  C言語で記述されたMarkdownパーサであり、ANSIに準拠している。

• MD4C

  C言語で記述されたMarkdownパーサであり、UTF-8に対応しており、HTMLレンダリングも可能である。