Strapdown.js
Bootstrap・Bootswatch テーマを適用する Markdown パーサ Strapdown.js についてまとめています。
Markdown を HTML に変換するだけの Markdown パーサはいくつか存在しますが、
Strapdown.js はこれに Bootstrap テーマおよび
Bootswatch が公開している Bootstrap テーマを適用します。
.html ファイル単体で Markdown を記載し、テーマを適用した Web サイトを
容易に(最小 1 ファイルだけで)公開できるメリットがあります。
複数ページになってくると構造が複雑になってきますし、
クローラーの収集として HTML ファイルになっている方が有利なので、
まともに Web サイトを構築するのは 静的サイトジェネータ が良いです。
MkDocs には Bootswatch を採用したテーマがあり、デザインはほぼそのままで、
TOC 付サイドバーとメニューを付けた Web サイトを容易に構築できます。
mkdocs/mkdocs-bootswatch | GitHub
🎈 Strapdown.js | 🎈 BALLOON | FU-SEN - English information
目次
公式サイト
注意
公式で使われていた独自ドメイン strapdownjs.com
は現在機能しなくなっています。
現在は jsDelivr の CDN を使用できますので、
オリジナルの Strapdown.js のまま CDN を使用したい場合は次に置き換えると良いでしょう。
<script src="https://cdn.jsdelivr.net/gh/arturadib/strapdown@gh-pages/v/0.2/strapdown.min.js"></script>
特徴・難点
<html>
<title>Strapdown.js のサンプル</title>
<xmp>
この中に **Markdown** を記載していきます。
</xmp>
<script src="https://cdn.jsdelivr.net/gh/arturadib/strapdown@gh-pages/v/0.2/strapdown.min.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://cdn.jsdelivr.net/gh/arturadib/strapdown@gh-pages/v/0.2/strapdown.min.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 はテーマが適用される点に注意を要します。
title
<title>タイトル</title>
とした場合、
ページ上部のヘッダは次の HTML ソースに展開されます。
<div id="headline" class="brand">タイトル</div>
場所的に <h1>
になっていそうですが、実際には <div>
です。
従って本文内の見出しは <h1>
、Markdown では #
から使用して下さい。
テーマ
<xmp>
または <textarea>
に theme
を入れて
Bootwatch で公開されている Bootstrap テーマを設定できます。
公式サイトなどは小文字に統一されていますが、
実際には頭文字が大文字のままでも使用できます。theme
記載なしは Bootstrap のデフォルトテーマになります。
オリジナルの Strapdown.js が採用されている Bootstrap は
Bootstrap 2 となります。
オリジナルで入っていない Cosmo と Flatly はthemes/
内に入れる事で指定して表示可能です。
🎈 fu-sen/strapdown | GitHub
🎈 fu-sen/strapdown.js | GitHub
ふうせん Fork 版
運営者が 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 すべて 20241129
で Marked v15.0.3 へ更新してあります。
<script src="https://cdn.jsdelivr.net/gh/fu-sen/strapdown.js@20241129/2/strapdown.min.js"></script>
<script src="https://cdn.jsdelivr.net/gh/fu-sen/strapdown.js@20241129/3/strapdown.min.js"></script>
4 のみ 20220726
で v4.6.2 のテーマへ更新してあります。
<script src="https://cdn.jsdelivr.net/gh/fu-sen/strapdown.js@20241129/4/strapdown.min.js"></script>
5 のみ 20230924
で v5.3.2 のテーマへ更新してあります。
<script src="https://cdn.jsdelivr.net/gh/fu-sen/strapdown.js@20241129/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 を使用する事ができます。
該当する 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">