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

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

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

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

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

.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/[email protected]/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 となります。
Bootstrap 4 と一部テーマが異なります。
オリジナルで入っていない Cosmo と Flatly は
themes/ 内に入れる事で指定して表示可能です。

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

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

20210515 で Marked v2.0.3 へ更新してあります。（以下同様）

<script src="https://cdn.jsdelivr.net/gh/fu-sen/[email protected]/2/strapdown.min.js"></script>

Bootstrap 3 | Bootwatch

更に Bootstrap 3 テーマ適用の Strapdown.js を入れてあります。
ただし、表示に不具合があったので、独自に修正しています。

<script src="https://cdn.jsdelivr.net/gh/fu-sen/[email protected]/3/strapdown.min.js"></script>

Bootstrap 4 | Bootwatch

また運営者が Bootstrap 4 および Bootstrap 5 の
テーマに対応した Strapdown.js も入れました。

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

20210508 で一部テーマの修正が入っているので、更新しています。

<script src="https://cdn.jsdelivr.net/gh/fu-sen/[email protected]/4/strapdown.min.js"></script>

Bootwatch

20210515 で Bootstrap v5.0.1 のテーマへ更新してあります。

<script src="https://cdn.jsdelivr.net/gh/fu-sen/[email protected]/5/strapdown.min.js"></script>

上記は安定版で、随時ビルドして更新している URL が別途存在します。

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

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

また、Bootstrap 3・4・5 ベータ版では navbar の色を更に選択できます。
（2021/03/10 コミットより）

Bootstrap 4・5 ベータ版は navbar="dark" または navbar="light" を指定できます。
省略時のデフォルトは navbar="primary" です。

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

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

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

特に Bootstrap 5 ベータ版は正式版になった後、
テーマが変更する可能性がありますので、ご注意下さい。

Markdown

次で Markdown での記載と表示結果を一覧しています。

🎈 Strapdown.js | md-parser.balloon.net.eu.org

SEO 対策

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

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

また、<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 は使用できますか？

<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

目次

公式サイト

特徴・難点