MarkdownのドキュメントをWebサイトとして公開するにあたって、通常のリンク貼り付けのみではどうしても華やかさに欠けてしまうため、カード型のリンクを試してみました

ブラウザ上からの編集について

ブラウザ上でGitBookのサイトにアクセスすればGUIの操作で完結が可能なのですが、筆者は普段そちらを使用していないので、ここではローカルのVSCode等で書いていきます

何なら、ブラウザ上からファイルの編集を行うのはあまりオススメしません・・・

簡単に説明すると、GitBookでの目次はSUMMARY.mdというファイルを作成してカスタマイズするのですが、そもそもカスタマイズせず自動生成に頼った方が圧倒的に楽なので、私はGitBook用のリポジトリにSUMMARY.mdを置いていません

しかし、ブラウザ上でファイルの編集を行うと、その際にSUMMARY.mdが自動生成されてしまい、次回以降ローカルでファイルを編集する際にSUMMARY.mdを削除する、又は整合性が合うように中身を編集する必要が生じてしまいます

上記の理由から、ファイルの編集はローカルの環境で行うことを推奨します

カード形リンクの作り方

以下のようなHTMLを記述すると、GitBook上ではカード形のリンクとして振る舞います

<table data-view="cards">
  <thead>
    <tr>
      <th></th>
      <th data-hidden data-card-cover data-type="files"></th>
      <th data-hidden data-card-target data-type="content-ref"></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Page1へのリンク</td>
      <td><a href="img/page1.jpg">thumbnail</a></td>
      <td><a href="page1.md">page1.md</a></td>
    </tr>
    <tr>
      <td>Page2へのリンク</td>
      <td><a href="img/page2.jpg">thumbnail</a></td>
      <td><a href="page2.md">page2.md</a></td>
    </tr>
    <tr>
      <td>Sub-Pageへのリンク</td>
      <td><a href="sub-page/img/sub.jpg">thumbnail</a></td>
      <td><a href="sub-page/README.md">sub-page/README.md</a></td>
    </tr>
    <tr>
      <td>外部へのリンク(Google)</td>
      <td><a href="img/google.jpg">thumbnail</a></td>
      <td><a href="https://www.google.com/">Google</a></td>
    </tr>
  </tbody>
</table>

こちらで実際の挙動を確認出来ます

ここでは、<tr>~</tr>で囲まれた部分が1つのカードとして機能します

この部分を増やすことでカードの数を増やすことが可能です

また、<td>~</td>に囲まれた部分によってカードの情報を指定します

1つ目にはカードのタイトル、2つ目にはカードに表示するサムネイル画像、3つ目にはリンク先を指定します

リンク先については、ドキュメント内の別ページを指定する際はmarkdownファイルの相対パスを指定します　また外部リンクを指定する際はURLをそのまま指定します

メリット・デメリット

メリットは言わずもがな、Webページの華やかさ・分かりやすさが増します

デメリットはWebページ上でしかレイアウト・リンクが機能しない事です　残念ながら、VSCodeやObsidianといったエディタ上でリンクをクリックしても、正しく遷移しません

折角Markdownで管理している訳ですから、リンクが機能しないというのは少々勿体ないですね

これについては、「個別のページではカード形式のリンクを使用せず、目次などでのみ使用する」という方針で妥協しています

個別のページでカードを使用してしまうと、もしGitBookから他の静的サイトジェネレータ(Hugo等)へ乗り換えた際に、内容とは関係なしに修正の必要が生じてしまいます

目次であれば、そもそもHugoでしたらタグやカテゴリーを付与して自動分類に頼ることになりますから、そのページ自体が不要になります　従って修正を加える必要はありません

要は、GitBookという環境で必要なファイルに対してのみカードを使用する、という事ですね

カードの使用にあたってはメリット・デメリットがありますが、やはりWebページの視認性が上がることは捨てがたいですから、GitBookを静的サイトジェネレータ代わりに使用している方々は是非とも導入してみてください・・・