playbooks

home / skills / ntaksh42 / agents / document-formatter

document-formatter skill

/.claude/skills/document-formatter

This skill formats Markdown, HTML, and text into clean, professional documents with automatic TOC, styling, and accessibility improvements.

npx playbooks add skill ntaksh42/agents --skill document-formatter

Review the files below or copy the command above to add this skill to your agents.

Files (3)
SKILL.md
15.2 KB
---
name: document-formatter
description: Format and style documents with consistent formatting. Use when standardizing document formatting or cleaning up text.
---

# Document Formatter Skill

ドキュメントの体裁を整え、美しく読みやすいフォーマットに変換するスキルです。

## 概要

このスキルを使用すると、乱れたMarkdownドキュメント、書きかけのメモ、構造化されていないテキストを、プロフェッショナルで読みやすいドキュメントに自動的に整形できます。

## 主な機能

- **Markdownフォーマット整形**: 見出し、リスト、コードブロックの統一
- **目次の自動生成**: 見出しから階層的な目次を作成
- **スタイルガイド適用**: 一貫したライティングスタイル
- **美しいHTML変換**: GitHub風やプロフェッショナルなデザイン
- **コードハイライト**: シンタックスハイライト付きコードブロック
- **テーブル整形**: 綺麗に整列されたテーブル
- **リンク検証**: 壊れたリンクの検出と修正提案
- **画像最適化**: altテキストの追加、サイズ指定
- **印刷最適化**: PDF出力に適したレイアウト

## 使用方法

### 基本的な使い方

```
以下のMarkdownドキュメントを整形してください：

[乱れたMarkdownを貼り付け]
```

### 目次の追加

```
このドキュメントに目次を追加してください：
位置: 冒頭
スタイル: 番号付き
深さ: 3階層まで
```

### HTML変換

```
このMarkdownを美しいHTMLに変換：
スタイル: GitHub風
コードハイライト: 有効
印刷対応: はい
```

### スタイルガイド適用

```
このドキュメントをMicrosoft Style Guideに従って整形：
- 見出しは文頭のみ大文字
- リストは並列構造
- コードは明示的に
```

## 整形機能

### 1. 見出しの整形

**修正内容**:
- 階層構造の修正（H1 → H2 → H3の順序）
- 見出しの前後に適切な空行
- 見出しレベルのスキップを防止
- 一貫した見出しスタイル

**整形前**:
```markdown
### はじめに
# プロジェクト名
## 機能
#### 詳細
```

**整形後**:
```markdown
# プロジェクト名

## はじめに

## 機能

### 詳細
```

### 2. リストの整形

**修正内容**:
- インデントの統一（2スペースまたは4スペース）
- マーカーの統一（`-`, `*`, `+`のいずれか）
- ネストレベルの修正
- リスト項目の並列構造

**整形前**:
```markdown
* 項目1
  - サブ項目1-1
    * サブサブ項目1-1-1
-項目2
   + サブ項目2-1
```

**整形後**:
```markdown
- 項目1
  - サブ項目1-1
    - サブサブ項目1-1-1
- 項目2
  - サブ項目2-1
```

### 3. コードブロックの整形

**修正内容**:
- 言語指定の追加
- インデントの統一
- コードのフォーマット（Prettier、Black等）
- シンタックスハイライト対応

**整形前**:
```
```
function hello(){
console.log("Hello")
}
```
```

**整形後**:
```markdown
​```javascript
function hello() {
  console.log("Hello");
}
​```
```

### 4. テーブルの整形

**修正内容**:
- 列の整列
- ヘッダーとボディの分離線
- セル内の余白統一
- Markdown表の正しい構文

**整形前**:
```markdown
| 名前 | 年齢|職業|
|---|---|---|
|田中|30|エンジニア|
|佐藤|25|デザイナー|
```

**整形後**:
```markdown
| 名前 | 年齢 | 職業         |
|------|------|--------------|
| 田中 | 30   | エンジニア   |
| 佐藤 | 25   | デザイナー   |
```

### 5. リンクと画像の整形

**修正内容**:
- URLの正規化
- リンクテキストの改善
- 画像のaltテキスト追加
- 相対パスの修正

**整形前**:
```markdown
[こちら](http://example.com)
![](image.png)
```

**整形後**:
```markdown
[Example サイト](https://example.com)
![プロジェクトのロゴ](image.png)
```

### 6. 引用の整形

**修正内容**:
- 引用マーカーの統一
- ネストされた引用の整形
- 出典の明記

**整形前**:
```markdown
>これは引用です
> >ネストされた引用
```

**整形後**:
```markdown
> これは引用です
>
> > ネストされた引用
```

## 目次生成

### 自動目次生成

見出しから自動的に目次を生成します。

**オプション**:
- **位置**: 冒頭、末尾、カスタム位置
- **深さ**: H2まで、H3まで、H4まで
- **スタイル**: 番号付き、箇条書き
- **アンカーリンク**: 有効/無効

**生成例**:
```markdown
# ドキュメントタイトル

## 目次

1. [はじめに](#はじめに)
2. [インストール](#インストール)
   1. [前提条件](#前提条件)
   2. [手順](#手順)
3. [使用方法](#使用方法)
   1. [基本的な使い方](#基本的な使い方)
   2. [高度な使い方](#高度な使い方)
4. [FAQ](#faq)

## はじめに

[内容...]
```

### カスタム目次

```
目次を生成：
- H2とH3のみ含める
- 「はじめに」「謝辞」は除外
- 番号付きリスト
- クリック可能なアンカーリンク
```

## スタイルガイド

### 1. Google Developer Documentation Style Guide

**特徴**:
- 簡潔で明確な文章
- アクティブボイス優先
- 第二人称（you）の使用
- 技術用語の一貫性

**適用例**:
```
整形前: "The button can be clicked by users"
整形後: "Click the button"

整形前: "It is recommended that..."
整形後: "We recommend..."
```

### 2. Microsoft Writing Style Guide

**特徴**:
- 見出しは文頭のみ大文字（Sentence case）
- 並列構造のリスト
- 手順は番号付きリスト
- 明確な指示語

**適用例**:
```
整形前: "How To Install The Software"
整形後: "How to install the software"

整形前:
- Installing
- Configuration
- To run

整形後:
- Install the software
- Configure the settings
- Run the application
```

### 3. AP Stylebook

**特徴**:
- ニュース・ブログ記事向け
- 日付形式の統一
- 数字の表記ルール
- 略語の明記

### 4. APA Style（学術論文）

**特徴**:
- フォーマルな文体
- 引用の標準化
- 参考文献リスト
- セクション構造

### 5. カスタムスタイル

独自のスタイルルールを定義できます：

```
カスタムスタイルで整形：
- 見出し: すべて大文字
- リスト: 常に番号付き
- コードブロック: 必ず言語指定
- リンク: 常に新しいタブで開く指定
```

## HTML変換

### GitHub風スタイル

**特徴**:
- GitHub Markdownと同じ見た目
- シンタックスハイライト
- テーブルスタイル
- レスポンシブ対応

**出力例**:
```html
<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="github-markdown.css">
  <style>
    .markdown-body {
      max-width: 980px;
      margin: 0 auto;
      padding: 45px;
    }
  </style>
</head>
<body class="markdown-body">
  [変換されたHTML]
</body>
</html>
```

### プロフェッショナルスタイル

**特徴**:
- ビジネスドキュメント向け
- 印刷最適化
- ページ番号、ヘッダー/フッター
- 目次、索引

### 技術文書スタイル

**特徴**:
- API仕様書、マニュアル向け
- サイドバーナビゲーション
- コード例のコピーボタン
- 検索機能

### ブログ記事スタイル

**特徴**:
- 読みやすいタイポグラフィ
- アイキャッチ画像
- SNSシェアボタン
- コメント欄

## コードハイライト

### サポート言語

以下の言語でシンタックスハイライトを適用：

- **C/C++**: GCC、MSVC、Clang
- **C#**: .NET、Unity
- **Python**: Python 3.x
- **JavaScript/TypeScript**: Node.js、ブラウザ
- **Java**: Java 8+
- **Go**: Go 1.x
- **Rust**: Rust 2021
- **SQL**: PostgreSQL、MySQL、SQL Server
- **Shell**: Bash、PowerShell
- **Markup**: HTML、XML、JSON、YAML
- その他50以上の言語

### テーマ

```
コードハイライトテーマ:
- github (デフォルト)
- monokai
- solarized-light
- solarized-dark
- dracula
- nord
- atom-one-dark
- vs-code
```

### 機能

- **行番号**: 表示/非表示
- **ハイライト行**: 特定の行を強調
- **差分表示**: 追加/削除行の表示
- **コピーボタン**: ワンクリックでコピー

**例**:
```markdown
​```javascript {2-3} showLineNumbers
function calculate(a, b) {
  const sum = a + b;  // この行をハイライト
  return sum;         // この行もハイライト
}
​```
```

## テーブルフォーマット

### 自動整列

列幅を自動計算して整列：

**整形前**:
```markdown
|Name|Age|Occupation|
|-|-|-|
|John|30|Engineer|
|Jane|25|Designer|
```

**整形後**:
```markdown
| Name | Age | Occupation |
|------|-----|------------|
| John | 30  | Engineer   |
| Jane | 25  | Designer   |
```

### セルの配置

```markdown
| Left | Center | Right |
|:-----|:------:|------:|
| 左   | 中央   |   右  |
```

### 複雑なテーブル

- セル結合の提案
- HTMLテーブルへの変換
- CSVからの変換

## リンク検証

### 壊れたリンクの検出

```
リンクチェック:
✓ [GitHub](https://github.com) - OK (200)
✗ [Broken](https://example.com/404) - Not Found (404)
? [Internal](#section) - セクションが存在しません
```

### 修正提案

```
修正提案:
- [こちら] → より説明的なリンクテキストに変更
- http:// → https:// に変更
- 相対パス → 絶対パスに変更（オプション）
```

## 画像最適化

### altテキストの追加

```markdown
整形前: ![](logo.png)
整形後: ![会社ロゴ](logo.png)
```

### サイズ指定

```markdown
整形前: ![Logo](logo.png)
整形後: ![Logo](logo.png){width=300}

HTML:
<img src="logo.png" alt="Logo" width="300">
```

### 画像の配置

```markdown
中央揃え:
<p align="center">
  <img src="logo.png" alt="Logo">
</p>
```

## 特殊機能

### 1. フロントマター追加

YAML形式のメタデータを追加：

```yaml
---
title: "ドキュメントタイトル"
author: "作成者名"
date: 2024-06-15
tags: [markdown, documentation]
---

# ドキュメント本文
```

### 2. 脚注の整形

```markdown
本文[^1]

[^1]: 脚注の内容
```

### 3. 定義リスト

```markdown
Term 1
: Definition 1

Term 2
: Definition 2a
: Definition 2b
```

### 4. タスクリスト

```markdown
- [x] 完了したタスク
- [ ] 未完了のタスク
- [ ] 別の未完了タスク
```

### 5. 数式（LaTeX）

```markdown
インライン数式: $E = mc^2$

ブロック数式:
$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$
```

## 整形ルール

### 改行と空行

```
ルール:
- 見出しの前後: 2行の空行
- 段落間: 1行の空行
- リストの前後: 1行の空行
- コードブロックの前後: 1行の空行
- テーブルの前後: 1行の空行
```

### 文字幅

```
推奨設定:
- 1行の最大文字数: 80文字（コード）、100文字（文章）
- 自動折り返し: 有効
- ソフトラップ: 単語境界で折り返し
```

### インデント

```
設定:
- リスト: 2スペースまたは4スペース
- コードブロック: 言語の規約に従う
- 引用: 自動インデント
```

## 出力形式

### 1. Markdown

整形されたMarkdownファイル：
- 標準Markdown
- GitHub Flavored Markdown (GFM)
- CommonMark
- Markdown Extra

### 2. HTML

```
HTML変換オプション:
- スタンドアロン（CSS埋め込み）
- 外部CSSリンク
- インライン CSS
- JavaScript含む/含まない
```

### 3. PDF

```
PDF生成:
- ページサイズ: A4、Letter、カスタム
- マージン: 標準、狭い、広い
- ヘッダー/フッター: カスタマイズ可能
- ページ番号: 位置、形式
- 目次: 自動生成
- しおり: 見出しから生成
```

### 4. Word (DOCX)

Pandoc形式でWord文書に変換

### 5. 他の形式

- reStructuredText
- AsciiDoc
- LaTeX
- MediaWiki

## カスタマイズ

### 整形ルールのカスタマイズ

```yaml
# .markdownlint.yaml
MD001: true  # 見出しレベルのインクリメント
MD003:
  style: atx  # 見出しスタイル
MD004:
  style: dash  # リストマーカー
MD013:
  line_length: 100  # 行の最大長
MD024: false  # 重複する見出しを許可
```

### テンプレート

独自のHTMLテンプレートを使用：

```html
<!DOCTYPE html>
<html>
<head>
  <title>{{title}}</title>
  <style>
    /* カスタムCSS */
  </style>
</head>
<body>
  {{content}}
</body>
</html>
```

## ユースケース

### 1. 既存ドキュメントの整形

```
この古いREADMEを最新のベストプラクティスに従って整形:
- 目次を追加
- コードブロックに言語指定
- テーブルを整列
- リンクを検証
```

### 2. 下書きから完成版へ

```
このメモを正式なドキュメントに:
入力: 箇条書きのメモ
出力: 構造化されたMarkdown + HTML
```

### 3. 複数ドキュメントの統一

```
以下の3つのドキュメントを同じスタイルで統一:
スタイルガイド: Google
フォーマット: 厳密
```

### 4. GitHub README の改善

```
このREADMEを改善:
- バッジを追加
- 目次を生成
- コード例を整形
- スクリーンショットの配置を最適化
```

### 5. 技術文書のHTML変換

```
API仕様書をHTMLに変換:
スタイル: 技術文書
サイドバー: 有効
検索: 有効
コピーボタン: すべてのコードブロックに
```

## ベストプラクティス

### 1. 一貫性

- 同じプロジェクト内では同じスタイルガイドを使用
- インデント、マーカー、見出しスタイルを統一
- 用語の一貫性（例: "e-mail" vs "email"）

### 2. 可読性

- 適切な空行で区切る
- 長い段落は分割
- リストを効果的に使用
- コード例は最小限で明確に

### 3. アクセシビリティ

- 画像にaltテキスト
- リンクテキストは説明的に
- テーブルにヘッダー
- 適切な見出し階層

### 4. SEO（Web公開時）

- メタデータの追加
- 説明的な見出し
- キーワードの適切な使用
- 内部リンク構造

## トラブルシューティング

### よくある問題

**問題**: テーブルが崩れる
**解決**: パイプ文字のエスケープ、列数の確認

**問題**: コードブロックが正しく表示されない
**解決**: 言語指定の確認、バックティックの数

**問題**: リンクが機能しない
**解決**: アンカーテキストの正規化、パスの確認

**問題**: 日本語の折り返しがおかしい
**解決**: word-break設定、フォント指定

## 制限事項

- 非常に大きなドキュメント（10MB以上）は処理時間がかかる可能性
- 複雑なHTMLの埋め込みは一部機能しない場合がある
- PDF生成はフォントによって制限される場合がある

## バージョン情報

- スキルバージョン: 1.0.0
- サポートMarkdown: CommonMark, GFM
- HTML変換: Markdown-it ベース
- PDF生成: Puppeteer/wkhtmltopdf

---

**使用例:**

```
このドキュメントを整形してください：

[乱れたMarkdownを貼り付け]

要件:
- 目次を追加（H2とH3のみ）
- コードブロックに言語指定
- テーブルを整列
- GitHub風HTMLも生成
```

このプロンプトで、プロフェッショナルに整形されたドキュメントが生成されます！

Overview

This skill formats and styles documents to a consistent, professional layout. It cleans up messy Markdown or plain text, enforces style rules, and can output polished Markdown, HTML, PDF, or DOCX. Use it to standardize documentation, prepare web-ready articles, or generate print-friendly files.

How this skill works

The formatter analyzes headings, lists, code blocks, tables, links, and images to normalize structure and spacing. It applies chosen style guides or custom rules, adds optional front matter and a generated table of contents, and validates links and image alt text. Outputs include GitHub-style HTML, business-ready HTML, PDF with bookmarks, and formatted Markdown or Word files.

When to use it

  • Standardizing multiple docs to a single style guide (Google, Microsoft, AP, APA, or custom)
  • Converting draft notes or messy Markdown into a clean, publishable document
  • Generating GitHub-friendly HTML or print-ready PDF from Markdown
  • Cleaning tables, aligning columns, and adding table headers
  • Adding language tags and syntax highlighting to code blocks

Best practices

  • Pick one style guide per project and apply it consistently across files
  • Enable front matter for metadata when producing multiple outputs
  • Limit line length for prose (100 chars) and code (80 chars) to improve readability
  • Include descriptive link text and alt text for all images for accessibility
  • Run link validation after content changes and before publishing

Example use cases

  • Improve a repository README: add a TOC, fix code blocks, align tables, and generate GitHub-style HTML
  • Turn scattered meeting notes into a structured Markdown doc with headings, task lists, and front matter
  • Batch-process three internal manuals to the Google style guide and export as PDF with page numbers
  • Convert API docs to technical HTML with sidebar navigation, copy buttons, and syntax-highlighted examples
  • Validate and repair links in a long document and suggest https upgrades for insecure URLs

FAQ

Which output formats are supported?

Markdown (GFM/CommonMark), HTML (standalone or templated), PDF, and DOCX via Pandoc.

Can I enforce a custom style?

Yes. Supply a custom rule set or .markdownlint-style config to control heading levels, markers, line length, and other options.