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();
 }

<br<

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-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;
 }