codegrid-markdown

CodeGridの記事で使われているMarkdown拡張記法を含んだ、markedベースのMarkdownライブラリーです。

動作環境

Node.js 24以上が必要です。

使い方

パッケージのインストール

npm i codegrid-markdown

Node.jsスクリプトでの実行

import fs from 'node:fs';
import CodeGridMarkdown from 'codegrid-markdown';

const CGMDRenderer = new CodeGridMarkdown({
  // options for marked
});

const str = fs.readFileSync(import.meta.dirname + '/cg.md', 'utf-8');
const htmlStr = CGMDRenderer.render(str);

CLIでの実行

cgmd ./path/to/your.md

# or
cgmd ./path/to/your.md -o ./path/to/your.html

# can also
cgmd '# foo'

CGMD記法

以下の2パターンの拡張があります。

• CodeGridで使うコラムや注釈を実現するCGMD拡張ブロック
• Markdownのコードブロックにタイトルを付与する拡張

CGMD拡張ブロックは、互いにネストできません。

note

本文を.Noteで包み、内部の見出しをタイトルとして表示する注釈ボックスを作成します。

[note]
#### 注釈タイトル

注釈本文
[/note]

↓

<div class="Note">
  <h4>注釈タイトル</h4>
  <p>注釈本文</p>
</div>

column

.Columnで囲んでコラム風の補足ブロックに仕立てます。

[column]
#### コラムタイトル

コラム本文
[/column]

↓

<div class="Column">
  <h4>コラムタイトル</h4>
  <p>コラム本文</p>
</div>

demo

.Demoコンテナを生成し、インラインフレームでのデモ表示を行います。ソースリンクの設置や遅延iframeにも対応します。

[demo]
# DEMOタイトル

<iframe src="http://example.com/demo.html"></iframe>
[/demo]

↓

<section class="CG2-livecode">
  <header class="CG2-livecode__header">
    <div class="CG2-livecode__label">
      DEMOタイトル
    </div>
    <div class="CG2-livecode__nav">
      <ul>
        <li>
          <a href="http://example.com/demo.html" target="_blank">
            <span class="CG2-icon-tool"></span> 新規タブで開く
          </a>
        </li>
      </ul>
    </div>
  </header>
  <div class="CG2-livecode__body">
    <iframe src="http://example.com/demo.html"></iframe>
  </div>
</section>

クリックで再生モードにしたい場合。

[demo]
# DEMOタイトル

<iframe data-src="http://example.com/demo.html" data-deferred="data-deferred"></iframe>
[/demo]

ソースコードへのリンクが欲しい場合。

[demo]
# DEMOタイトル
[ソースコード](http://example.com)

<iframe src="http://example.com/demo.html"></iframe>
[/demo]

imgbox

<figure class="ImgBox">に変換し、タイトル、画像とキャプションをひとまとまりに表示します。

[imgbox]
#### 画像タイトル
画像の説明

![画像alt](http://example.com/image.png)
[/imgbox]

↓

<figure class="ImgBox">
  <h4>画像タイトル</h4>
  <p>画像の説明</p>
  <p><img src="http://example.com/image.png" alt="画像alt"></p>
</figure>

tree

Markdownのリストを<details>付きのインタラクティブなファイルツリーに組み替えます。

[tree]
#### ファイルツリー
- src/
  - styles/
    - base.css
  - **components/**
    - **a-lot-of-files/**
[/tree]

<div class="Tree">
  <h4>ファイルツリー</h4>
  <ul>
    <li class="directory">
      <details>
        <summary>src/</summary>
        <ul>
          <li class="directory">
            <details>
              <summary>styles/</summary>
              <ul>
                <li class="file" data-file-type="css">base.css</li>
              </ul>
            </details>
          </li>
        </ul>
          <li class="directory">
            <details>
              <summary><strong>components/</strong></summary>
              <ul>
                <li class="directory">
                  <details>
                    <summary><strong>a-lot-of-files/</strong></summary>
                    <ul>
                      <li data-file-type class="file">...</li>
                    </ul>
                  </details>
                </li>
              </ul>
            </details>
          </li>
      </details>
    </li>
  </ul>
</div>

code（タイトルつき）

Markdownのコードブロックにタイトルを付与する拡張です。

```html#素敵なdiv
<div></div>
```

GFMのコードブロックで、Syntaxに続けて#コードのタイトルを指定すると、以下が出力されます。

<section class="CG2-livecode">
  <header class="CG2-livecode__header">
    <div class="CG2-livecode__label">素敵なdiv</div>
  </header>
  <div class="CG2-livecode__body">
    <pre><code class="language-html">
      &lt;div&gt;&lt;/div&gt;
    </code></pre>
  </div>
</section>

コードのタイトル指定がない場合、通常のMarkdownのコードブロックとして処理されます。

コードの修正・機能追加

メンテナンスモードに入っていますが、バグ修正や軽微な機能追加を行いたい場合は以下を参考にしてください。

ランタイムの全体像

lib/index.jsがトークナイザ・レンダラ・トランスフォーマを束ねてMarkdownをHTMLに変換します。新しい機能はここから呼び出される既存の拡張点を利用してください。処理の流れを追うにはlib/tokenizer/→lib/renderer/→lib/transformer/の順に読むと把握しやすいです。

拡張記法

cgmdのレンダラはlib/renderer/cgmd/に追加し、lib/renderer/cgmd.jsに登録します。DOMレベルの整形はlib/transformer/に置きます。小さな単位のレンダラを作り、必要に応じてlib/renderer/md/の既存実装を参考にしてください。

CLIとサンプル

bin/cgmd.jsがcgmdコマンドを提供します。ローカルでHTML出力を試すにはexample/main.jsを使うかnpm run exampleを実行して挙動を確認できます。CLIの引数追加や既定値の変更はbin/cgmd.jsを編集してください。

テスト

テストはtest/以下に配置し、Node組み込みテストで実行します。

コマンド	説明
npm test	全テストを実行
npm run test:watch	ファイル変更を監視しながら反復実行
npm run test:update-snapshots	スナップショットを更新

テストの配置：

• レンダラ：test/cgmd/renderer/
• トークナイザ：test/cgmd/tokenizer/
• トランスフォーマ：test/cgmd/transformer/
• CLI：test/cgmd/cli.js

スナップショットテスト

CLIのテスト（test/cgmd/cli.js）はnode:testのスナップショット機能（t.assert.snapshot()）を使っています。スナップショットはtest/cgmd/cli.js.snapshotに保存されており、コミット対象です。

CLIの出力が意図的に変わった場合はnpm run test:update-snapshotsでスナップショットを更新してからコミットしてください。

開発の流れ

• 環境：Node.js 24以上が必要です
• 依存を整える：npm ci
• 実装を加える：拡張はlib/renderer/cgmd/、DOM整形はlib/transformer/
• 動作確認：サンプルのnpm run exampleまたは最小入力での単体実行
• テスト：失敗→修正→npm run test:watchで反復
• スナップショット更新：CLIの出力が変わった場合はnpm run test:update-snapshots
• ドキュメント：新しい記法やオプションはREADME.mdに追記

LICENSE

MIT License