codegrid-markdown

v7.0.1

Published

10 days ago

CodeGrid-specified markdown processor.

0High
0Medium
0Low

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のコードブロックにタイトルを付与する拡張です。

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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

codegrid-markdown

動作環境

使い方

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

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

CLIでの実行

CGMD記法

note

column

demo

imgbox

tree

code（タイトルつき）

コードの修正・機能追加

ランタイムの全体像

拡張記法

CLIとサンプル

テスト

スナップショットテスト

開発の流れ

LICENSE