document-formatter

Document Formatter Skill

This skill formats documents and converts them into a beautiful, easy-to-read format.

Overview

With this skill, you can automatically format messy Markdown documents, half-finished notes, and unstructured text into professional, easy-to-read documents.

Key Features

Markdown Formatting: Unify headings, lists, and code blocks
Automatic Table of Contents Generation: Create a hierarchical table of contents from headings
Style Guide Application: Consistent writing style
Beautiful HTML Conversion: GitHub-style or professional design
Code highlighting: Code blocks with syntax highlighting
Table Formatting: Neatly aligned tables
Link Validation: Detection of broken links and fix suggestions
Image Optimization: Adding alt text, specifying sizes
Print Optimization: Layout suitable for PDF output

Usage

Basic Usage

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

[乱れたMarkdownを貼り付け]

Adding a Table of Contents

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

HTML Conversion

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

Applying a Style Guide

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

Formatting Features

1. Heading Formatting

Fixes:

Fixing the hierarchy (order of H1 → H2 → H3)
Appropriate blank lines before and after headings
Preventing skipped heading levels
Consistent heading style

Before Formatting:

### はじめに
# プロジェクト名
## 機能
#### 詳細

After Formatting:

# プロジェクト名

## はじめに

## 機能

### 詳細

2. List Formatting

Fixes:

Unifying indentation (2 spaces or 4 spaces)
Unifying markers (-, *, +one of)
Fixing nesting levels
Parallel structure of list items

Before Formatting:

* 項目1
  - サブ項目1-1
    * サブサブ項目1-1-1
-項目2
   + サブ項目2-1

After Formatting:

- 項目1
  - サブ項目1-1
    - サブサブ項目1-1-1
- 項目2
  - サブ項目2-1

3. Code Block Formatting

Fixes:

Adding language specification
Unifying indentation
Code formatting (Prettier, Black, etc.)
Syntax highlighting support

Before Formatting:

function hello(){ console.log("Hello") }

After Formatting:

```javascript
function hello() {
  console.log("Hello");
}
```

4. Table Formatting

Fixes:

Column alignment
Separator line between header and body
Unifying padding within cells
Correct Markdown table syntax

Before Formatting:

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

After Formatting:

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

5. Link and Image Formatting

Fixes:

URL normalization
Improving link text
Adding alt text to images
Fixing relative paths

Before Formatting:

[こちら](http://example.com)
![](image.png)

After Formatting:

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

6. Quote Formatting

Fixes:

Unifying quote markers
Formatting nested quotes
Specifying sources

Before formatting:

>これは引用です
> >ネストされた引用

After formatting:

> これは引用です
>
> > ネストされた引用

Table of contents generation

Automatic table of contents generation

Automatically generates a table of contents from headings.

Options:

Position: beginning, end, custom position
Depth: Up to H2, up to H3, up to H4
Style: numbered, bulleted
Anchor links: enabled/disabled

Generation example:

# ドキュメントタイトル

## 目次

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

## はじめに

[内容...]

Custom table of contents

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

Style guide

1. Google Developer Documentation Style Guide

Features:

Concise and clear sentences
Prefer active voice
Use of second person (you)
Consistency of technical terms

Application examples:

整形前: "The button can be clicked by users"
整形後: "Click the button"

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

2. Microsoft Writing Style Guide

Features:

Headings use sentence case (capitalize only the first word)
Lists with parallel structure
Procedures use numbered lists
Clear directives

Application examples:

整形前: "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

Features:

For news and blog articles
Unified date format
Rules for writing numbers
Spelling out abbreviations

4. APA Style (academic papers)

Features:

Formal writing style
Standardized citations
Reference list
Section structure

5. Custom styles

You can define your own style rules:

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

HTML conversion

GitHub-style

Features:

Same appearance as GitHub Markdown
Syntax highlighting
Table styles
Responsive support

Output example:

<!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>

Professional style

Features:

For business documents
Print optimization
Page numbers, headers/footers
Table of contents, index

Technical documentation style

Features:

For API specifications and manuals
Sidebar navigation
Copy button for code examples
Search function

Blog article style

Features:

Readable typography
Featured image
Social share buttons
Comment section

Code highlighting

Supported languages

Applies syntax highlighting in the following languages:

C/C++: GCC、MSVC、Clang
C#: .NET、Unity
Python: Python 3.x
JavaScript/TypeScript: Node.js, browser
Java: Java 8+
Go: Go 1.x
Rust: Rust 2021
SQL: PostgreSQL、MySQL、SQL Server
Shell: Bash、PowerShell
Markup: HTML、XML、JSON、YAML
More than 50 other languages

Theme

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

Features

Line numbers: show/hide
Highlighted lines: emphasize specific lines
Diff display: display added/deleted lines
Copy button: One-click copy

Example:

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

Table formatting

Automatic alignment

Automatically calculates column widths and aligns:

Before formatting:

|Name|Age|Occupation|
|-|-|-|
|John|30|Engineer|
|Jane|25|Designer|

After formatting:

| Name | Age | Occupation |
|------|-----|------------|
| John | 30  | Engineer   |
| Jane | 25  | Designer   |

Cell alignment

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

Complex tables

Suggestions for cell merging
Conversion to HTML tables
Conversion from CSV

Link validation

Detection of broken links

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

Fix suggestions

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

Image optimization

Adding alt text

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

Size specification

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

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

Image placement

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

Special features

1. Add front matter

Add YAML-format metadata:

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

# ドキュメント本文

2. Formatting footnotes

本文[^1]

[^1]: 脚注の内容

3. Definition lists

Term 1
: Definition 1

Term 2
: Definition 2a
: Definition 2b

4. Task list

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

5. Mathematical formulas (LaTeX)

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

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

Formatting rules

Line breaks and blank lines

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

Character width

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

Indentation

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

Output format

1. Markdown

Formatted Markdown file:

Standard Markdown
GitHub Flavored Markdown (GFM)
CommonMark
Markdown Extra

2. HTML

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

3. PDF

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

4. Word (DOCX)

Convert to Word document in Pandoc format

5. Other formats

reStructuredText
AsciiDoc
LaTeX
MediaWiki

Customization

Customizing formatting rules

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

Templates

Use a custom HTML template:

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

Use cases

1. Formatting existing documents

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

2. From draft to final version

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

3. Unifying multiple documents

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

4. Improving GitHub README

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

5. Converting technical documents to HTML

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

Best practices

1. Consistency

Use the same style guide within the same project
Unify indentation, markers, and heading styles
Terminology consistency (e.g., "e-mail" vs "email")

2. Readability

Separate with appropriate blank lines
Split long paragraphs
Use lists effectively
Keep code examples minimal and clear

3. Accessibility

Alt text for images
Make link text descriptive
Headers in tables
Appropriate heading hierarchy

4. SEO (when publishing on the web)

Adding metadata
Descriptive headings
Appropriate use of keywords
Internal link structure

Troubleshooting

Common problems

Problem: Tables break Solution: Escape pipe characters, check the number of columns

Problem: Code blocks do not display correctly Solution: Check the language specification and the number of backticks

Problem: Links do not work Solution: Normalize anchor text, check paths

Problem: Japanese line wrapping is incorrect Solution: word-break settings, font specification

Limitations

Very large documents (10MB or more) may take time to process
Some features may not work when embedding complex HTML
PDF generation may be limited depending on fonts

Version information

Skill version: 1.0.0
Supported Markdown: CommonMark, GFM
HTML conversion: Markdown-it based
PDF generation: Puppeteer/wkhtmltopdf

Usage example:

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

[乱れたMarkdownを貼り付け]

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

With this prompt, professionally formatted documents will be generated!

About this skill

Overview

Key Features

Usage

Basic Usage

Adding a Table of Contents

HTML Conversion

Applying a Style Guide

Formatting Features

1. Heading Formatting

2. List Formatting

3. Code Block Formatting

4. Table Formatting

5. Link and Image Formatting

6. Quote Formatting

Table of contents generation

Automatic table of contents generation

Custom table of contents

Style guide

1. Google Developer Documentation Style Guide

2. Microsoft Writing Style Guide

3. AP Stylebook

4. APA Style (academic papers)

5. Custom styles

HTML conversion

GitHub-style

Professional style

Technical documentation style

Blog article style

Code highlighting

Supported languages

Theme

Features

Table formatting

Automatic alignment

Cell alignment

Complex tables

Link validation

Detection of broken links

Fix suggestions

Image optimization

Adding alt text

Size specification

Image placement

Special features

1. Add front matter

2. Formatting footnotes

3. Definition lists

4. Task list

5. Mathematical formulas (LaTeX)

Formatting rules

Line breaks and blank lines

Character width

Indentation

Output format

1. Markdown

2. HTML

3. PDF

4. Word (DOCX)

5. Other formats

Customization

Customizing formatting rules

Templates

Use cases

1. Formatting existing documents

2. From draft to final version

3. Unifying multiple documents

4. Improving GitHub README

5. Converting technical documents to HTML

Best practices

1. Consistency

2. Readability

3. Accessibility

4. SEO (when publishing on the web)

Troubleshooting

Common problems

Limitations

Version information