Bootstrap・Bootswatch テーマを適用する Markdown パーサ Strapdown.js についてまとめています。

Markdown を HTML に変換するだけの Markdown パーサはいくつか存在しますが、
Strapdown.js はこれに Bootstrap テーマおよび
Bootswatch が公開している Bootstrap テーマを適用します。

.html ファイル単体で Markdown を記載し、テーマを適用した Web サイトを
容易に（最小 1 ファイルだけで）公開できるメリットがあります。

複数ページになってくると構造が複雑になってきますし、
クローラーの収集として HTML ファイルになっている方が有利なので、
まともに Web サイトを構築するのは静的サイトジェネータが良いです。

🎈 Mkdocs | ふうせん🎈 FU-SEN

MkDocs には Bootswatch を採用したテーマがあり、デザインはほぼそのままで、
TOC 付サイドバーとメニューを付けた Web サイトを容易に構築できます。

mkdocs/mkdocs-bootswatch | GitHub

🎈 Strapdown.js | 🎈 BALLOON | FU-SEN - English information

.html の中に Markdown を記載する事で、JavaScript で HTML に変換に表示します。
このようなものを Markdown パーサ と言いますが、
他の Markdown ポーサと異なる点に Bootstrap テーマを適用する点が挙げられます。
Markdown で記載して、容易にテーマを適用した Web サイトを構築できます。
1 ファイル単体で完結し、サーバにアップロードしなくても
ローカルで実際に表示を確認する事ができます。

JavaScript で変換されるため、変換は Web ブラウザで行われます。
そのためページの行数が長くなる程、Web ブラウザには負荷となります。
あまり大きなサイズの表示には適していません。

また、Google などの検索エンジンが参照してくるクローラーは
JavaScript で変換する前のテキストを参照し、検索結果へ反映します。
そのため、クローラーは Markdown で記載されている装飾を理解できません。
回避策として、特に認識してほしいリンクや画像などを HTML タグで記載する方法があります。

上記に加えて、ページ数が増えてくると、ファイル・メニュー構成など、
ファイル管理が複雑になってきます。
複数ページを生成してまともに Web サイトを公開するのであれば、
静的サイトジェネレータを使用するのが無難でしょう。
🎈 Hugo や 🎈 Jekyll などがありますが、
MkDocs には Strapdown.js で採用されているテーマと同じ
Bootswatch のテーマが存在しています。
パソコンでの表示では通常サイドバーにページ見出しを表示します。

MkDocs
🎈 MkDocs | ふうせん🎈 FU-SEN
mkdocs/mkdocs-bootswatch | GitHub

記載方法

上にあったサンプルより、より詳細に記載する事もできます。

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8" />
  <title>Strapdown.js のサンプル</title>
  <meta name="description" content="Strapdown.js のサンプル結果を表示します。" />
</head>
<body>
<textarea theme="simplex">
`<xmp>` の代わりに `<textarea>` を使用できます。  
</textarea>
<script src="https://strapdownjs.com/v/0.2/strapdown.js"></script>
</body>
</html>

🎈 ソース | GitHub
🎈 表示結果 | strapdown-js.balloon.net.eu.org

公式サイトのサンプルでは非表示にするため、 style="display:none;" が付加されています。

<textarea theme="united" style="display:none;">

しかし、これがなくても一瞬変換前の状態が見えるだけで、大きな支障はありません。
SEO 的な考慮から記載しない方が良いと記載しないケースもあります。
実際に運営者が試した感じでは style="display:none;" が付いていても、
正常に Google で検索結果に反映されるように見えます。

<head> 内は通常の HTML 同様に記載して構いません。JavaScript も有効ですが、
CSS はテーマが適用される点に注意を要します。

CDN

オリジナルで採用されている strapdownjs.com は CDN が採用されていません。
現在は jsDelivr の CDN を使用できますので、
オリジナルの Strapdown.js のまま CDN を使用したい場合は次に置き換えると良いでしょう。

<script src="https://cdn.jsdelivr.net/gh/arturadib/strapdown@gh-pages/v/0.2/strapdown.min.js"></script>

title

<title>タイトル</title> とした場合、
ページ上部のヘッダは次の HTML ソースに展開されます。

<div id="headline" class="brand">タイトル</div>

場所的に <h1> になっていそうですが、実際には <div> です。
従って本文内の見出しは <h1> 、Markdown では # から使用して下さい。

テーマ

<xmp> または <textarea> に theme を入れて
Bootwatch で公開されている Bootstrap テーマを設定できます。
公式サイトなどは小文字に統一されていますが、
実際には頭文字が大文字のままでも使用できます。
theme 記載なしは Bootstrap のデフォルトテーマになります。

Bootstrap 2 | Bootwatch

オリジナルの Strapdown.js が採用されている Bootstrap は
Bootstrap 2 となります。
オリジナルで入っていない Cosmo と Flatly は
themes/ 内に入れる事で指定して表示可能です。

🎈 fu-sen/strapdown | GitHub
🎈 fu-sen/strapdown.js | GitHub

運営者が Fork して最新状態を反映し、テーマ Cosmo と Flatly も入れてあります。
Fork したソースと実ファイルそのものは strapdown ですが、
jsDelivr を用いた CDN で直接 Web で使用できるよう、
更に strapdown.js で専用プロジェクトを作ってあります。

Bootstrap 3 | Bootwatch
Bootstrap 4 | Bootwatch
Bootwatch

現在 Bootstrap は Bootstrap 5 が最新です。
合わせて Bootswatch テーマも制作・公開されているのですが、
これら Bootstrap 3～5 のテーマを適用した Strapdown.js も公開してあります。

Bootstrap 4 から仕様が変わっているため、CSS を追加・変更しています。
2・3 とは見た目が変わるところがあります。ご注意下さい。

2～5 すべて 20230322 で Marked v4.3.0 へ更新してあります。

<script src="https://cdn.jsdelivr.net/gh/fu-sen/strapdown.js@20230322/2/strapdown.min.js"></script>

<script src="https://cdn.jsdelivr.net/gh/fu-sen/strapdown.js@20230322/3/strapdown.min.js"></script>

4 のみ 20220726 で v4.6.2 のテーマへ更新してあります。

<script src="https://cdn.jsdelivr.net/gh/fu-sen/strapdown.js@20230322/4/strapdown.min.js"></script>

5 のみ 20221211 で v5.2.3 のテーマへ更新してあります。

<script src="https://cdn.jsdelivr.net/gh/fu-sen/strapdown.js@20230322/5/strapdown.min.js"></script>

@ 後の日付部分を main に変更すると、常に最新版を参照します。
ただしテーマ仕様の変更などで急に表示が変化する恐れがあります。

<script src="https://cdn.jsdelivr.net/gh/fu-sen/strapdown.js@main/2/strapdown.min.js"></script>

<script src="https://cdn.jsdelivr.net/gh/fu-sen/strapdown.js@main/3/strapdown.min.js"></script>

<script src="https://cdn.jsdelivr.net/gh/fu-sen/strapdown.js@main/4/strapdown.min.js"></script>

<script src="https://cdn.jsdelivr.net/gh/fu-sen/strapdown.js@main/5/strapdown.min.js"></script>

使用できるテーマは次のところにあるそれぞれの index.html で一覧表示できます。

🎈 strapdown-js.balloon.net.eu.org

また、3・4・5 では navbar の色を更に選択できます。（20210310 より）
4・5 は navbar="dark" または navbar="light" を指定できます。
省略時のデフォルトは navbar="primary" です。

<textarea theme="yeti" navbar="light">

3 は navbar="inverse" でテーマ定義のもう一色を適用します。

<textarea theme="yeti" navbar="inverse">

SEO 対策

クローラーは Markdown 状態のテキストを参照する事になります。
検索結果に反映される事を考慮すると、次は HTML タグで記載した方が良いです。
逆にこの仕組みを利用して Markdown で記載する事で
あえて検索結果に出にくくする事もできます。

リンク <a> - リンク先をクローラーが参照できます。
画像 <img> - 画像が検索結果に表示されます。
見出し <h1> ～ <h6> - 見出しが検索結果に出てくる事があります。

また、<meta name="description"> を <head> 内に入れる事で、
検索結果のテキストに表示できるので、理想的にできるでしょう。

<title>Strapdown.js テスト</title>
<meta name="description" content="Strapdown.js を使用した Web サイトの公開テストを行ってみました。">

Bootstrap Components

Strapdown.js では Bootstrap テーマを採用しているため、
Bootstrap Components を使用する事ができます。

ドキュメント Components | Bootstrap

該当する HTML タグを使用する場所に記載して下さい。
Strapdown.js は HTML タグ内の Markdown を変換しないため、
中の装飾も HTML タグで記載する必要があります。

派生

機能の不足を補うため、追加機能や派生が生まれています。

joedf/strapdown-topbar | GitHub
オリジナル版 Strapdown.js の後に追加する事で、ヘッダーにメニューを追加できます。
おまけで左上にロゴを追加する logo.js もあります。
ページ運営者公開版ではオリジナルと同じ Bootstrap 2 版に限り適用できます。
ndossougbe/strapdown | GitHub
左サイドバーに見出しの一覧（TOC＝Table Of Contents）を表示します。
ページ運営者公開版ではオリジナルと同じ Bootstrap 2 版に限り適用できます。
chaitin/strapdown-zeta | GitHub
MathJax 対応、見出しの一覧、 highlight.js 対応など。
Bootstrap は Bootstrap 3 ベースで、Bootswatch テーマも更新されています。
Naereen/StrapDown.js | GitHub
詳しい説明。Strapdown.js もヘッダなどの改良が見られます。
テーマはオリジナルからいくつか追加されていますが、
オリジナル版の Bootstrap 2 ベースに独自対応しているようです。

Q&A

スマートフォンに対応していますか？

はい。レスポンシブデザイン対応で、スマートフォンサイズの横幅で表示されます。

Google の検索結果で表示されますか？

運営者が実際に使用している限り、Google の検索結果には正常に表示されます。
ただし、 Google などは Markdown の構文を認識しません。
検索結果の説明文である <meta name="description"> を使用し、
また、リンクは <a href="～"> 、画像は <img src="～"> と HTML タグを使用すると、
その部分は追って参照する事を期待できます。
ページランクが高くなると、見出しも <h1> ～ <h6> で効果が出てきます。

表示結果や Google などの検索結果で文字化けしています。

最近の Web サービスでは .html を Content-Type: text/html; charset=utf-8 と
文字コード UTF-8 で記載されている前提で設定されているのですが、
長年運用されている古い HTML の表示を考慮したレンタルサーバや Web サービスでは
UTF-8 などの Unicode が定義される以前で、文字コードがバラバラだったため、
.html を Content-Type: text/html と定義され、文字コードが未定義になっています。
解決手段として <title> タグの上に次を追加して下さい。

<meta charset="utf-8">

これで .html ファイルが文字コード UTF-8 である事を定義し、
期待する結果が得られるようになります。

独自の CSS を適用したいのですが、テーマが適用されてしまいます。

テーマの CSS は strapdown.js を読み込んだ時に適用されます。それは <body> の直前です。

<script src="https://strapdownjs.com/v/0.2/strapdown.js"></script>
</body>

従って、 strapdown.js の後、<body> の前に CSS を入れる必要があります。

<script src="https://strapdownjs.com/v/0.2/strapdown.js"></script>
<link rel="stylesheet" href="sample.css">
</body>

もちろんここに <style> で囲って直接記載しても構いません。

<script src="https://strapdownjs.com/v/0.2/strapdown.js"></script>
<style>
a {
    color: #0088ff;
}
</style>
</body>

OGP は使用できますか？

The Open Graph protocol
🎈 Open Graph protocol | ふうせん🎈 FU-SEN

<head> へ普通に追加できるので、
OGP（OpenGraph）および Teitter Card の情報を付加して適用できます。

<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="タイトル">
<meta name="twitter:description" content="説明">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:image" content="https://example.net.eu.org/ogp.png">
<meta property="og:type" content="website">
<meta property="og:title" content="タイトル">
<meta property="og:description" content="説明">
<meta property="og:site_name" content="サイト名">
<meta property="og:image" content="https://example.net.eu.org/ogp.png">

Strapdown.js

目次

公式サイト

特徴・難点