🔍

Zenn記事のフロントマターを自動チェックするツールを作ってみた

2025/05/01に公開

 はじめにZennでは、Markdownファイルのフロントマター（メタデータ部分）を使って記事や本の情報を管理しています。しかし、記事や本が増えてくると、フロントマターの記述が一貫していないという問題が発生しがちです。必須項目の漏れや順序の不一致などがあると、サイトの品質や保守性に影響します。
私自身、Zennで複数の記事や本を管理するうちに、フロントマターの書き方が記事ごとにバラバラになっていることに気づきました。特にチーム内で執筆を分担する場合など、フォーマットの統一が課題になります。そこで個人的に、Zenn向けのMarkdownファイルを自動でチェックして修正できるツールを作成しました。
今回は、この個人制作ツールである「tool-lint-md」を紹介します。このツールを使えば、一貫性のある記事・本の管理が可能になります。

 Zenn公式のMarkdown管理について先に、Zenn公式のMarkdown管理の仕組みについて簡単に説明します。

 Zenn CLIZennでは「Zenn CLI」というツールを使って、ローカル環境で記事を執筆・管理することができます。基本的な使い方は以下の通りです：
# Zenn CLIのインストール
npm init --yes
npm install zenn-cli

# プロジェクトの初期化
npx zenn init

# 新しい記事の作成
npx zenn new:article

# プレビュー開始
npx zenn preview
初期化後、以下のようなディレクトリ構造が作成されます：
.
├── articles/     # 記事を格納するディレクトリ
├── books/        # 本を格納するディレクトリ
├── .gitignore
├── package.json
└── README.md
記事ファイルはarticles/ディレクトリ内に、本はbooks/ディレクトリ内に配置します。各ファイルのフロントマターには、タイトル、絵文字、タグなどの情報を記述します。
Zenn CLIは基本的な管理機能を提供していますが、フロントマターの一貫性をチェックする機能は含まれていません。ここに私の作成したツールが役立ちます。

 ツールの概要tool-lint-mdは、Zenn向けの記事(articles)および本(books)のフロントマタープロパティを検証・整形するためのツールです。

主な機能は以下の通りです：
フロントマタープロパティの必須チェック (コンテンツタイプ別)
プロパティの順序チェック
slugの形式チェック
本のconfig.yamlのチェック
章の番号付けとファイル名のチェック
自動修正機能 (--fix オプション付きで実行時)
カスタム設定ファイルのサポート
テスト機能 (--test オプションで実行可能)
このツールを導入することで、記事や本の品質を一定に保ち、Zennコンテンツ全体の一貫性を維持することができます。

 MDとMDXの違いこのツールを理解する前に、MDとMDXの違いを簡単に説明しておきます：

MD (Markdown): 軽量マークアップ言語で、プレーンテキストに簡単な書式を追加するもの

MDX: JSXをMarkdownに組み込んだもので、React コンポーネントをMarkdown内で使用可能
このツールはZenn形式のMarkdownファイル専用です。MDXファイルには現在まだ対応していません。

※これから良い感じに対応できるようになるかもしれませんが（　＾ω＾）・・・

 インストール方法以下のコマンドでリポジトリをクローンし、必要な依存関係をインストールします：
# リポジトリのクローン
git clone https://github.com/telosh/tool-lint-md.git
cd tool-lint-md

# 依存関係のインストール
npm install
あるいは、既存のプロジェクトに組み込む場合は、必要なファイルをコピーして使用することもできます。

 使用方法
 基本的な使い方検証のみを行う場合：
npm run lint:zenn
検証と自動修正を行う場合：
npm run lint:zenn:fix

 直接実行する場合ts-nodeを使って直接実行することもできます：
# 検証のみ
npx ts-node scripts/lint-zenn.ts

# 自動修正
npx ts-node scripts/lint-zenn.ts --fix

# テストモードでの実行
npx ts-node scripts/lint-zenn.ts --test

 Zennの記事・本のフロントマター
 記事（article）のフロントマター---
title: "記事のタイトル"
emoji: "😸" # アイキャッチとして使われる絵文字（1文字）
type: "tech" # tech: 技術記事 / idea: アイデア記事
topics: ["markdown", "zenn", "npm"] # タグ（1〜5つまで）
published: true # 公開設定（falseで下書き）
published_at: 2023-06-15 # 公開日時（省略可能）
---

 本の設定ファイル（config.yaml）title: "本のタイトル"
summary: "本の紹介文"
topics: ["markdown", "zenn", "npm"] # トピック（5つまで）
published: true # 公開設定（falseで下書き）
price: 0 # 無料の場合は0、有料の場合は500〜5000
chapters:
  - chapter1
  - chapter2

 カスタマイズ設定zenn-lint.config.json ファイルを作成することで、リンターの動作をカスタマイズできます。以下は設定例です：
{
  "propertyOrder": [
    "title",
    "emoji",
    "type",
    "topics",
    "published",
    "published_at"
  ],
  "requiredProperties": {
    "article": ["title", "emoji", "type", "topics", "published"],
    "bookChapter": ["title"],
    "default": ["title", "published"]
  },
  "bookConfigRequiredProperties": [
    "title",
    "summary",
    "topics",
    "published",
    "price",
    "chapters"
  ],
  "contentPattern": "articles/**/*.md",
  "contentTypePatterns": {
    "article": ["articles/"],
    "bookChapter": ["books/"]
  }
}

 設定オプションの説明

オプション
説明


propertyOrder
フロントマタープロパティの推奨順序

requiredProperties
コンテンツタイプ別の必須プロパティ

bookConfigRequiredProperties
本のconfig.yamlの必須プロパティ

contentPattern
Markdownファイルの検索パターン

contentTypePatterns
コンテンツタイプを判定するためのパスパターン


 検証内容このツールは以下の内容を検証します：
記事のフロントマターの必須プロパティと順序
記事のスラッグ（ファイル名）の有効性
本のconfig.yamlの必須プロパティ
本のチャプター構成の正しさ
本のチャプターのフロントマター
チャプターのファイル名が数字.スラッグ.md形式に準拠しているか
重複したチャプタースラッグがないか

 実装のポイントこのツールは主にTypeScriptで実装されています。核となる機能は以下の通りです：
Markdownファイルの検索と読み込み
フロントマターの解析
コンテンツタイプの判定（記事か本のチャプターか）
プロパティの検証（必須項目と順序）
自動修正（必要に応じて）
特に、コンテンツタイプによって必須項目が異なる仕様に対応している点が実用的です。また、本のチャプターの順序や命名規則を自動でチェックできる点も便利です。

 まとめZenn向けのMarkdownファイルで記事や本を管理している場合、フロントマターの一貫性は非常に重要です。tool-lint-mdを導入することで、以下のメリットが得られます：
記事や本のメタデータ品質の向上
チーム内での一貫した記事作成
CIパイプラインに組み込むことで自動的な品質保証
このツールは個人的な制作物として公開していますが、Zennユーザーの皆さんのお役に立てれば幸いです。ぜひ自分のプロジェクトに合わせてカスタマイズし、Zennコンテンツ管理の効率化に役立ててください。
現在、TypeScriptの経験を深める目的で開発・メンテナンスを続けており、機能追加や改善を行っています。不具合や改善点がありましたらGitHubのIssueやこの記事へのコメントでお知らせください。フィードバックをもとに改善していきたいと思います！

 参考資料tool-lint-md GitHub リポジトリ
Zenn CLI ガイド

オプション	説明
propertyOrder	フロントマタープロパティの推奨順序
requiredProperties	コンテンツタイプ別の必須プロパティ
bookConfigRequiredProperties	本のconfig.yamlの必須プロパティ
contentPattern	Markdownファイルの検索パターン
contentTypePatterns	コンテンツタイプを判定するためのパスパターン

はじめに

Zenn公式のMarkdown管理について

Zenn CLI

ツールの概要

MDとMDXの違い

インストール方法

使用方法

基本的な使い方

直接実行する場合

Zennの記事・本のフロントマター

記事（article）のフロントマター

本の設定ファイル（config.yaml）

カスタマイズ設定

設定オプションの説明

検証内容

実装のポイント

まとめ

参考資料

Discussion