社内ブログ用のMarkdown to HTML変換ツールの作成 #HTML

はじめに

社内ブログを運営する上で、エンジニアにとってMarkdownは記事を書くのに便利な記法です。しかし、Markdownをそのまま公開することはできないため、HTMLに変換する必要があります。そこで、Markdownファイルを簡単にHTMLに変換するPythonツールを作成することにしました。

GitHub

簡単な動作サンプル

# sample-1

これはサンプルです

## sample h2
    
    ```bash
    # これはサンプルです
    date
    # これはサンプルです
    make install
    ```

### これはサンプルです

:::note info
インフォメーション
:::

:::note warn
ワーニング
:::

:::note alert
アラート
:::

このような状態のファイルが、次のような構造で存在している場合

sample
│  .markdownignore
│  サンプル_2.md
│  
└─適当なディレクトリ
        ignore.md
        sample_1.md

次のようにコマンドを打ちます

python .\main.py .\sample\ .\sample\public_sample --anchor-links

作成結果は次のようになります

sample
│  .markdownignore
│  サンプル_2.md
│
├─public_sample
│  │  ignore.html
│  │  index.html
│  │  sample_1.html
│  │  サンプル_2.html
│  │
│  ├─css
│  │      base.css
│  │      pygments.css
│  │
│  └─icon
│          alert.svg
│          info.svg
│          warn.svg
│
└─適当なディレクトリ
        ignore.md
        sample_1.md

sample_1.htmlは次のような具合になります。

また、自動でindex.htmlも作成されます

こちらにサンプルのリンクを置いておくのでソースコードなどが必要であればご確認ください。

要件

このツールに求める要件は以下の通りです：

Markdownファイルを指定されたディレクトリから読み込み、HTMLに変換する。
変換後のHTMLファイルを指定されたディレクトリに出力する。
.markdownignoreファイルを使用して、特定のファイルやディレクトリを無視する。
フラグを使用して、出力をカスタマイズできるようにする。

実装

Markdownの変換

Markdownの変換には、markdownパッケージを使用しました。以下のようにconvert_markdown_to_html関数を作成し、Markdownの変換を行います：

def convert_markdown_to_html(md_content, icon_dir, anchor_links):
    extensions = ['markdown.extensions.fenced_code', 'codehilite', 'markdown.extensions.toc']
    extension_configs = {
        'markdown.extensions.toc': {
            'anchorlink': anchor_links,
            'permalink': anchor_links,
            'toc_depth': '2-4',
        },
    }
    md = markdown.Markdown(extensions=extensions, extension_configs=extension_configs)

    html_content = md.convert(md_content)
    toc = md.toc

    html_content = convert_info_warn_error_blocks(html_content, icon_dir)

    if anchor_links:
        html_content = f"<div class='root'><div class='content'>{html_content}</div><div class='toc'>{toc}</div></div>"
    else:
        html_content = f"<div class='root'><div class='content'>{html_content}</div></div>"

    return html_content

.markdownignoreの処理

.markdownignoreファイルを使用して、特定のファイルやディレクトリを無視する機能を追加しました。以下のようにread_markdownignore関数を作成し、無視するパターンを読み込みます：

def read_markdownignore(doc_dir):
    markdownignore_path = os.path.join(doc_dir, ".markdownignore")
    if os.path.exists(markdownignore_path):
        with open(markdownignore_path, "r", encoding="utf-8") as file:
            return file.read().splitlines()
    return []

フラグによるカスタマイズ

フラグを使用して、出力をカスタマイズできるようにしました。以下のようなフラグを追加しました：

--index-only: インデックスファイルのみを生成する。
--no-index: インデックスファイルを生成しない。
--no-style: スタイルファイルをコピーしない。
--anchor-links: ページ内リンクを生成する。

これらのフラグは、validate_command_line_arguments関数で処理されます：

def validate_command_line_arguments():
    if "--help" in sys.argv:
        print_help()
        sys.exit(0)

    if len(sys.argv) < 3:
        print("使用法: python script.py <docフォルダのパス> <出力先> [オプション]")
        sys.exit(1)

    doc_dir = sys.argv[1]
    output_dir = sys.argv[2]
    index_only = "--index-only" in sys.argv
    no_index = "--no-index" in sys.argv
    no_style = "--no-style" in sys.argv
    anchor_links = "--anchor-links" in sys.argv

    return doc_dir, output_dir, index_only, no_index, no_style, anchor_links

今後の改善点

現在のツールにはいくつかの改善点があります：

エラー処理：現在、エラー処理が不十分です。突貫で作成したため、1ミリもエラー処理を行っていません、、
ログ出力：同じく現状はログ出力1ミリ（以下同…）
コードに関してもあまりよいとは言えない状態であるため、時間を見ながら改修していきたい。

これらの改善点については、今後のバージョンで対応していく予定です。

まとめ

今回作成したMarkdown to HTML変換ツールにより、社内ブログの記事をMarkdownで書き、簡単にHTMLに変換できるようになりました。.markdownignoreファイルを使用して不要なファイルを無視したり、フラグを使用して出力をカスタマイズしたりできるのが特徴です。

今後は、エラー処理やログ出力などの改善を行い、より使いやすいツールにしていきます。このツールを活用することで、社内ブログの運営がより効率的になることを期待しています。