npm module markdown-generator を TSで書き直し

4 年前に作った markdown-generator を刷新した.

こちら: @shuent/markdown-generator

モチベーション

無職になったこのタイミングでもう一回個人ブログを書く気になり，やっぱり git で md コンテンツを管理していきたい，と変わらず思った.

その時に前に作ったツールと自分が同じ気持ち:

ファイル名に日付入れて frontmatter セットしたものを効率的に scaffold md を生成したい，

でいることに気づき，この作ったツールを思い出した．

(Rails 育ちなので，ファイルを scaffold する，というアイディアが好き．)

今では vibe coding できるので TS と CLI のライブラリを使って作り直すことにした．TS は便利だけど commonjs, esm やトランスパイルやらでそのまま使えずセットアップがだるかったので commonjs をそのまま使ってたようだ．

今は AI への知識ソーシングのために markdown が盛り上がってる感じがする．ビジネス職でも cursor で Doc を md で書いていこう，みたいな投稿を見かける．なので，結構このツールが貢献できるケースが結構ある気がする．

なんでこのツールが有用なのか〜とかは README に詳しく書いてるので見てほしい. (英語ですが)

アップデート内容

v2 では、プロジェクト全体を TypeScript で書き直し、モダンなアーキテクチャに刷新した。

主な変更点

  • TypeScript 化: 型安全性の向上と IDE サポートの強化
  • 関数型プログラミング: Result 型によるエラーハンドリング、純粋関数による設計
  • 依存性注入: テスタビリティの向上とモジュール性の改善
  • ES Modules: CommonJS から ES Modules への移行
  • 設定ファイルの強化: cosmiconfig による柔軟な設定ファイル対応
    • mdg.config.js、mdg.config.ts、mdg.config.jsonなど複数形式に対応
    • Zod によるスキーマバリデーション

開発体験の向上

  • ビルドツール: tsup による高速ビルド
  • テスト: Vitest への移行、カバレッジレポート
  • コード品質: ESLint、Prettier、型チェックの統合

ユースケース

基本的な使い方は変わらず、より柔軟で強力になった。

基本的な使用例

# 初期設定
npx mdg init

# テンプレートから生成
npm run mdg blog "新しい記事のタイトル"

高度な設定例

mdg.config.ts:

import { defineConfig } from "@shuent/markdown-generator"

export default defineConfig({
  templates: {
    blog: {
      fileName: "{{date}}-{{slug}}.md",
      directory: "content/blog",
      template: "templates/blog.md",
      variables: {
        author: "shuent",
        category: () => process.env.DEFAULT_CATEGORY || "tech",
      },
      prompts: {
        tags: {
          type: "text",
          message: "タグをカンマ区切りで入力:",
          default: "blog",
        },
      },
    },
  },
})

新機能の活用

  • 動的変数: 関数として変数を定義し、実行時に値を生成
  • プロンプト: ユーザー入力による変数の設定
  • 複数テンプレート管理: プロジェクト内で複数のテンプレートを使い分け

ツールの使い方

インストール

npm install -D @shuent/markdown-generator

CLI コマンド

# テンプレート一覧
npx mdg list

# テンプレートから生成
npx mdg generate <template> <title>

# インタラクティブモード
npx mdg generate

npm scripts での使用

{
  "scripts": {
    "mdg": "mdg generate",
    "new:blog": "mdg generate blog",
    "new:note": "mdg generate note"
  }
}

v1 で学んだ「自分が欲しいものを作る」という精神は変わらず、より堅牢で拡張性の高いツールに進化した。TypeScript と関数型プログラミングの採用により、保守性も大幅に向上している。