SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsmarkdown-master

markdown-master

Coding & development

View repository

Updated 10-15 21:46

About this skill

Markdown Master

Preparation Before Use

First check and install dependencies:

# 检查 Python 是否可用
python --version

# 安装可选依赖（convert.py 需要）
pip install python-docx markdown beautifulsoup4 weasyprint pyyaml

Note:structure.py / quality.py / files.py Uses only the Python standard library; no additional installation is required. Only convert.py requires the above dependencies.

Core Workflow

Scenario 1: Preparing a Chinese document for formal release

When users need to organize a Markdown document into a formal version:

  1. First run a format check：python scripts/quality.py doc.md lint --fix
  2. Then optimize Chinese typography：python scripts/quality.py doc.md zhlint --fix
  3. Add section numbering：python scripts/structure.py doc.md numbering add --h1 "第{1}章 " --h2 "{1}.{2} " --h3 "（{3}）"
  4. Generate a table of contents：python scripts/structure.py doc.md toc generate
  5. Check links：python scripts/quality.py doc.md linkcheck
  6. Export to Word/PDF：python scripts/convert.py doc.md --to docx

Scenario 2: Merging multiple documents

When users have multiple Markdown files that need to be merged into one:

  1. Merge the files：python scripts/files.py merge file1.md file2.md -o combined.md
  2. Uniformly adjust heading levels(if needed):python scripts/structure.py combined.md heading upgrade --levels 1
  3. Subsequent steps same as Scenario 1(lint → zhlint → numbering → table of contents → export)

Scenario 3: Splitting a long document

When users have a very long document that needs to be split into multiple files by chapter:

  1. Split：python scripts/files.py split doc.md --by h2
  2. Check the split result

Command Quick Reference

structure.py — Structural Operations

Usage Description
python scripts/structure.py <file> heading upgrade [--levels N] Promote all headings by N levels (default 1)
python scripts/structure.py <file> heading downgrade [--levels N] Demote all headings by N levels
python scripts/structure.py <file> numbering add [--h1 T] [--h2 T] ... [--config FILE] [--start-from N] [--save-config FILE] Add flexible numbering, with each level's format configurable independently; supports loading configuration from YAML or saving the current configuration
python scripts/structure.py <file> numbering remove Remove all numbering
python scripts/structure.py <file> toc generate [--depth N] [--position top|after-h1] Insert/update the table of contents

All operations overwrite the original file by default; use -o output.md to output to a new file.

Numbering Template Syntax

Placeholder Meaning Example
{N} / {N:d} Decimal number 3
{N:02d} Two-digit zero-padded decimal number 03
{N:R} Uppercase Roman numeral III
{N:r} Lowercase Roman numeral iii
{N:A} Uppercase letter C
{N:a} Lowercase letter c
{N:cn} Chinese numeral 三

The N range is 1-6, corresponding to heading levels H1-H6. An empty template string means no numbering is added to that level's headings.

YAML Configuration File Format

h1: "第{1}章 "
h2: "{1}.{2} "
h3: "（{3}）"
h4: ""
h5: ""
h6: ""
start_from: 1

Common Numbering Usage Examples

# 技术文档风格（1/1.1/1.1.1）
python scripts/structure.py doc.md numbering add --h1 "{1} " --h2 "{1}.{2} " --h3 "{1}.{2}.{3} "

# 中文章节风格（第1章/1.1/（1））
python scripts/structure.py doc.md numbering add --h1 "第{1}章 " --h2 "{1}.{2} " --h3 "（{3}）"

# 学术风格（I/A/1/a）
python scripts/structure.py doc.md numbering add --h1 "{1:R} " --h2 "{2:A} " --h3 "{3} " --h4 "{4:a} "

# 保存当前配置为模板
python scripts/structure.py doc.md numbering add --h1 "第{1}章 " --h2 "{1}.{2} " --save-config chinese_chapter.yaml

# 使用保存的配置
python scripts/structure.py doc.md numbering add --config chinese_chapter.yaml

quality.py — Quality Check Operations

Usage Description
python scripts/quality.py <file> lint [--fix] Format compliance check;--fix automatically fixes fixable issues
python scripts/quality.py <file> zhlint [--fix] Chinese typography check;--fix automatically fixes
python scripts/quality.py <file> linkcheck [--check-remote] Local link/image check; add a parameter to check HTTP links

Output format:[L行号] 问题描述, then summarizes the issue count at the end. If there are no issues, outputs ✓ No issues found。

lint check items:

  • ✗ Heading level jump (H1 -> H3)
  • ✗ File is missing H1
  • ✓ 3 or more consecutive blank lines
  • ✗ Code block without a specified language

zhlint check items:

  • ✓ Missing space between Chinese and English/numbers
  • ✓ Half-width punctuation used in Chinese context

convert.py — format conversion

python scripts/convert.py <input.md 或 目录/ --to <format> [-o output] [--template template.docx]
Format Description
docx Word document, supports --template specifying a template
html Self-contained HTML (inline CSS)
txt Plain text (removes all Markdown markup)
pdf PDF (via weasyprint)

When the input is a directory, batch-convert all .md files.

files.py — file-level operations

# 拆分
python scripts/files.py split <input.md> --by h1|h2|h3 [--output-dir DIR]

# 合并（支持文件列表或目录）
python scripts/files.py merge <file1> [file2 ...] -o output.md [--separator SEP]

split outputs by default to <input_dir>/split_output/, with the filename XX_<标题文本>.md. When merge input is a directory, merge all .md files in alphabetical order by filename.