🍮

GitHubによるドキュメントサイト管理システムの構築 Part.3

2025/09/23に公開

GitHub Pagesを用いたドキュメント公開システムの構築についての記事の第3回です。

今回の詳細なコードは以下のGitHubにあります。

前回まででドキュメントサイトの基本的な仕組みは整いました。ただし、タグの導入などにより記事の投稿手順が煩雑になっています。

現状記事を書く際には以下のようにしなければなりません。

記事のタイトル、タグをfrontmatterに記載
記事を書く
記事に付与したタグに対してタグページを作成
※ タグページはfrontmatterだけが書かれた空ファイル
commit、devブランチにpush
mainブランチへのPRを作成
PRを承認

特に面倒なのは3.です。内容もない空ファイルを作成する手順というのは、サイトの仕組みを知らない人からすれば、なんのためにやっているのかわからないでしょう。記載ミスも起こり得ます。

そこでこれらを自動化するVSCode拡張を作りましょう。

VSCode拡張の仕様

上記のユースケースをもとに必要な機能を炙り出してみましょう。

記事のタイトル、タグをfrontmatterに記載
→記事のfrontmatterを自動で作りたい
記事を書く
→自動化できないが、書きながらMarkdownのプレビューが見たい
記事に付与したタグに対してタグページを作成
→タグページ用のファイル作成、Frontmatter記載を自動で行いたい
commit、devブランチにpush
→terminalでgitコマンドを叩くことなく、VSCode上で完結したい
mainブランチへのPRを作成
→VSCode上で完結したい
PRを承認
→管理者が行う作業のため自動化優先度は低い

2, 4, 5, 6についてはVSCodeの標準機能や、拡張を使うことで実現可能です。

番号	ユースケース	拡張
2	Markdownのプレビュー	VSCodeの標準機能
4	VSCode上でcommit, push	VSCodeの標準機能(PCにGitを導入している必要あり)
5, 6	PR作成、承認	GitHub Pull Request and Issues

ということで、作成しなければいけないのは1, 3の機能です。
機能を細かく分割すると、

1-1. 記事のタイトル、タグ情報を入力から受け取る
1-2. 記事、タグページを作成する
1-3. Frontmatterを記載する

これを実装しましょう。

VSCode拡張の作成

VSCodeはTypeScriptで簡単に作成できます。
以下のようなディレクトリ構成で作成します。

/
|-src/
|   |- extension.ts
|
|- package.json
|- tsconfig.json

package.jsonは以下のようにしました。

{
	"name": "manual-site-extension",
	"displayName": "VSCode to ManualSite Extension",
	"description": "マニュアルサイト操作用のVSCode拡張機能",
	"version": "0.0.1",
	"engines": {
		"vscode": "^1.60.0"
	},
	"activationEvents": [
		"onCommand:extension.createArticleTemplate"
	],
	"main": "./out/extension.js",
	"contributes": {
	"commands": [
			{
				"command": "extension.createArticleTemplate",
				"title": "Create Article: 新しい記事テンプレートを生成"
			}
		]
	},
	"scripts": {
		"vscode:prepublish": "tsc -p ./",
		"compile": "tsc -p ./",
		"watch": "tsc -watch -p ./"
	},
	"devDependencies": {
		"@types/node": "^18.0.0",
		"typescript": "^4.4.3",
		"vscode": "^1.1.37"
	},
	"repository": {
		"type": "git",
		"url": "https://github.com/PicricAcid/manual-site-extension.git"
	}
}

ポイントは

"contributes": {
	"commands": [
		{
			"command": "extension.createArticleTemplate",
			"title": "Create Article: 新しい記事テンプレートを生成"
		}
	]
}

の箇所です。ここにコマンドで実行する関数とタイトル(コマンドパレットに表示される)を記載します。また、activationEventにも関数の記載が必要です(VSCodeは要らないと言ってきますが、ないとうまくいかないことがあります)。

tsconfig.json配下です。特に変わったことはしていません。

{
    "compilerOptions": {
        "module": "commonjs",
        "target": "es6",
        "outDir": "out",
        "lib": ["es6"],
        "sourceMap": true,
        "rootDir": "src",
        "strict": true
    },
    "exclude": ["node_modules", ".vscode-test"]
}

最後にextension.tsとして以下を記載します。

import * as vscode from 'vscode';
import * as path from 'path';
import * as fs from 'fs';

async function createArticleTemplate() {
    const workspaceFolders = vscode.workspace.workspaceFolders;
    if (!workspaceFolders || workspaceFolders.length === 0) {
        vscode.window.showErrorMessage('ワークスペースが開かれていません。');
        return;
    }
    const root = workspaceFolders[0].uri.fsPath;

// 1-1. 記事のタイトル、タグ情報を入力から受け取る
    const title = await vscode.window.showInputBox({
        prompt: '記事のタイトルを入力してください',
        ignoreFocusOut: true,
    });
    if (!title) {
        vscode.window.showErrorMessage('タイトルが未入力のため中止します。');
        return; 
    }

    const author = await vscode.window.showInputBox({
        prompt: '著者名を入力してください',
        ignoreFocusOut: true
    });
    if (!author) {
        vscode.window.showErrorMessage('著者名が未入力のため中止します。');
        return;
    }
    
    const filename = await vscode.window.showInputBox({
        prompt: 'ファイル名(英数字・ハイフン・アンダーバーのみ)を入力してください(拡張子は自動生成されます)',
        ignoreFocusOut: true,
        placeHolder: 'example-article'
    });
    if (!filename || !/^[a-zA-Z0-9_-]+$/.test(filename)) {
        vscode.window.showErrorMessage('ファイル名が不正です。英数字、ハイフン、アンダーバーのみを使用してください。');
        return;
    }

    const tagInput = await vscode.window.showInputBox({
        prompt: 'タグ(スペース区切り, 空欄可)',
        ignoreFocusOut: true,
        placeHolder: 'tag1 tag2 tag3'
    });
    const tags = tagInput ? tagInput.trim().split(/\s+/) : [];

    const today = new Date().toISOString().slice(0, 10);

// 1-2. 記事、タグページを作成する
    const contentPath = path.join(root, 'docs', 'contents', `${filename}.md`);
    await fs.promises.mkdir(path.dirname(contentPath), { recursive: true });
    
    const tagDir = path.join(root, 'docs', 'tags');
    await fs.promises.mkdir(tagDir, { recursive: true });

// 1-3. Frontmatterを記載する
    const frontmatter = [
        `---`,
        `title: ${title}`,
        `author: ${author}`,
        `date: ${today}`,
        `lastmod: ${today}`,
        `tags: [${tags.map(tag => `${tag}`).join(', ')}]`,
        `---`,
        ``,
        `本文をここに記述してください。`,
        ``
    ].join('\n');
    
    await fs.promises.writeFile(contentPath, frontmatter, 'utf8');

    for (const tag of tags) {
        const tagFilePath = path.join(tagDir, `${tag}.md`);
        await fs.promises.writeFile(
            tagFilePath,
             `---\nlayout: tag\ntitle: ${tag}\ntag: ${tag}\n---\n`, 
             'utf8'
        );
    }

    vscode.window.showInformationMessage(`記事 "${title}" が作成されました: ${contentPath}`);
}  

export function activate(context: vscode.ExtensionContext) {
    context.subscriptions.push(
        vscode.commands.registerCommand('extension.createArticleTemplate', createArticleTemplate)
    );
}