目次

1.はじめに

Document In HTML(DIH)は、
あらゆるドキュメントをHTML形式にて生成することを目的とする。

2.基本構想

本項にて基本構想を説明する。

生成するドキュメントはHTML形式であるが、生成元たるファイルは用途ごとに以下のようになる。

用途 ファイル形式 数量
本文 MarkDown(.mdファイル) 生成する1つのHTMLファイルに対して1つのみ。
文章デザイン CSS(.cssファイル) 生成する1つのHTMLファイルに対して1つのみ。
または無し。
画像 PNG(.drawio.pngファイル)
SVG(.drawio.svgファイル)		 生成する1つのHTMLファイルに対して1つ以上。
または無し。

本文はMarkDown形式で記述する(デザインや文章構造によってはHTMLタグを用いることもある)。
文章デザインはCSS形式で記述する。
画像の描画はPNG形式を用いるが、より高度な図を描画したい場合はSVG形式を用いることもある。

これらのファイルを組み合わせて単一のHTMLファイルを生成する。
単一のHTMLファイルにするので、CSSファイルや画像ファイルはすべてHTMLファイルに埋め込む。
これにより、HTMLファイルのみでドキュメントを閲覧できるようになる。

HTMLファイルの生成は専用の変換スクリプトを用いて行う。
以下にHTMLファイルの生成過程を図解する。

図: img.2.img-1

3.開発環境

本項にて開発環境を説明する。

Python3 がインストールされていることが前提となる。
それ以外は特に指定をしない。

推奨する開発環境は以下の通りである。

4.チュートリアル

本項にてチュートリアルを示す。

4.a.本文のみのHTMLファイルを生成する

本文のみのHTMLファイルを生成するチュートリアルである。

4.a.1.変換スクリプトのインストール

md2html.pyを任意の作業ディレクトリに配置する。
必要な外部ライブラリをインストールする。

4.a.2.本文たるMarkdownファイルの作成

以下のMarkdownファイルを作成する。

example.md

# チュートリアル
これはチュートリアルです。

4.a.3.変換処理の実行

スクリプトを用いてHTMLファイルを生成する。

$ python3 md2html.py --src-md-path example.md --dist-html-path example.html

これにてexample.htmlが生成される。

4.b.文章デザインを適用したHTMLファイルを生成する

文章デザインを適用したHTMLファイルを生成するチュートリアルである。

4.b.1.変換スクリプトのインストール

md2html.pyを任意の作業ディレクトリに配置する。
必要な外部ライブラリをインストールする。

4.b.2.本文たるMarkdownファイルの作成

以下のMarkdownファイルを作成する。

example.md

# チュートリアル
これはチュートリアルです。

4.b.3.文章デザインたるCSSファイルの作成

以下のCSSファイルを作成する。

example.css

h1 {
    background-color: #64cadcff;
    padding: 6px 2px;
}

4.b.4.変換処理の実行

スクリプトを用いてHTMLファイルを生成する。

$ python3 md2html.py --src-md-path example.md --src-css-path example.css --dist-html-path example.html

これにて文章デザインを適用が適用されたexample.htmlが生成される。
また、CSSファイルのデータがHTMLファイルに埋め込まれている。

4.c.画像を埋め込んだHTMLファイルを生成する

画像を埋め込んだHTMLファイルを生成するチュートリアルである。

4.c.1.変換スクリプトのインストール

md2html.pyを任意の作業ディレクトリに配置する。
必要な外部ライブラリをインストールする。

4.c.2.本文たるMarkdownファイルの作成

以下のMarkdownファイルを作成する。

example.md

# チュートリアル
これはチュートリアルです。

![画像](./images/img.1.img-1.drawio.png)

Markdownの記法にて画像を埋め込む記述する。

4.c.3.画像ファイルの配置

以下の画像ファイルを配置する。

  • ./images/img.1.img-1.drawio.png

画像ファイルの作成・編集はdraw.ioのツールを用いて行うものとする。

4.c.4.変換処理の実行

スクリプトを用いてHTMLファイルを生成する。

$ python3 md2html.py --src-md-path example.md --dist-html-path example.html

これにて画像が埋め込まれたexample.htmlが生成される。
また、画像ファイルのデータがHTMLファイルに埋め込まれている。

5.より高度な使い方

本項にてより高度な使い方について説明する。

5.a.インデント

本文中にインデントを用いることができる。
インデントはPython-MarkdwonのAdmonition拡張機能を用いる。

5.a.1.CSSファイルの記述

インデントのスタイルを記述するためのCSSファイルに以下の記述をする。

example.css

.indent {
    padding-left: 20px;　/* これにより右に字下げ */
    border-left: 1px solid #eeeeee;　/* 左側の線 */
}

5.a.2.本文へのインデントの記述

本文中でインデントを用いる際は以下のように記述する。

example.md

# インデント
!!! indent ""
    ここにインデントする文章を記述する。

この文章はインデントされない。

これにてインデントされた文章が生成される。

付録

変換スクリプト

スクリプト本文

https://github.com/TakumaYoshikawa/dih/blob/master/src/docs/md2html.py

スクリプト起動方法

スクリプトは以下のようにして起動する。

$ python3 md2html.py --src-md-path _edit0_index.md --src-css-path edit0.css --dist-html-path index.html

コマンドライン引数説明

引数名 必須 説明
--src-md-path ○ 変換元のMarkdownファイルのパス
--src-css-path - 変換元のCSSファイルのパス
--dist-html-path ○ 変換先のHTMLファイルのパス

必要な外部ライブラリ

スクリプトは以下の外部ライブラリを使用する。

拡張機能カススタイズ

スクリプト本文中の# 拡張機能を有効化の部分にて拡張機能のカスタマイズを行うことができる。
カスタマイズにあたってはPython-Markdown公式ドキュメントを参照すること。

生成元ファイルのサンプル

本ドキュメントの生成元たるファイルの一式はここ。