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

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

 Bootswatch

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

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

🎈 Mkdocs | ふうせん🎈 FU-SEN

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

 mkdocs/mkdocs-bootswatch | GitHub


目次


公式サイト

 Strapdown.js
 arturadib/strapdown | GitHub


特徴・難点

<html>
<title>Strapdown.js のサンプル</title>
<xmp>
この中に **Markdown** を記載していきます。
</xmp>
<script src="https://strapdownjs.com/v/0.2/strapdown.js"></script>
</html>

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

.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">