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


目次


公式サイト

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 や 🎈 GitHub Pages などの
静的サイトジェネレータを用いて HTML に変換した状態で公開するのが無難でしょう。


記載方法

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

<!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> から、Markdown では # から使用できます。

テーマ

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

Bootstrap 2 | Bootwatch

オリジナルで採用されている 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 で専用プロジェクトを作ってあります。次に置き換えて下さい。

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

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

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

Bootstrap 3 | Bootwatch

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

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

Bootstrap 4 | Bootwatch

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

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

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

Bootstrap は Bootstrap 5 が開発中です。
テーマも対応され次第、Bootstrap 5 向けも用意したいと思っています。

Markdown

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

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

Bootstrap Components

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

ドキュメント Components | Bootstrap

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


派生

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

  • joedf/strapdown-topbar
    通常の Strapdown.js の後に追加する事で、ヘッダーにメニューを追加できます。
    おまけで左上にロゴを追加する logo.js もあります。

  • ndossougbe/strapdown | GitHub
    左サイドバーに見出しの一覧(TOC=Table Of Contents)を表示します。

  • chaitin/strapdown-zeta | GitHub
    MathJax 対応、見出しの一覧、 highlight.js 対応など。

  • Naereen/StrapDown.js | GitHub
    詳しい説明。Strapdown.js もヘッダなどの改良が見られます。

  • 🎈 fu-sen/strapdown | GitHub
    Bootstrap 2 テーマ追加、Bootstrap 3・4 版を入れてあります。運営者が公開しています。

  • 🎈 fu-sen/strapdown.js | GitHub
    上のソースでビルドした Strapdown.js を jsDelivr CDN で使用できます。


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>