html-semantic-optimizer

HTML semantic optimization tool

Automatically converts generic HTML tags into semantic HTML5 tags, improving code accessibility and SEO friendliness.

Quick Start

Install Dependencies

pip install beautifulsoup4 lxml

Command-Line Usage

# 优化单个文件
python scripts/optimize.py input.html -o output.html

Dry Run (Preview Results)

python scripts/optimize.py input.html --dry-run

Use Custom Rules

python scripts/optimize.py input.html --rules custom_rules.json

Batch Process Directory

python scripts/batch_optimize.py /path/to/html/files/ -o /output/dir/

Batch Process (Recurse Subdirectories)

python scripts/batch_optimize.py /path/to/html/files/ --recursive -o /output/dir/

### Python API 使用

```python
from html_optimizer import optimize_html

# 使用默认规则
result = optimize_html('<div class="btn">点击</div>')
# 输出: <button class="btn" type="button">点击</button>

# 自定义规则
from html_optimizer import RuleEngine, DOMTransformer

rules = [
    {"name": "侧边栏", "keywords": ["sidebar"], "target_tag": "aside", "priority": 8}
]

engine = RuleEngine(rules)
transformer = DOMTransformer(engine)
result = transformer.transform(html_content)

How It Works

The tool analyzes the CSS class names of elements, matches predefined rules, and converts generic tags into the corresponding HTML5 semantic tags:

Keyword	Target Tag	Example
btn, button	<button>	<div class="btn"> → <button>
link, nav-link	<a>	<div class="link"> → <a>
header, top-bar	<header>	<div class="header"> → <header>
nav, navbar	<nav>	<div class="nav"> → <nav>
footer, bottom	<footer>	<div class="footer"> → <footer>
main, content	<main>	<div class="main"> → <main>
article, post	<article>	<div class="article"> → <article>
sidebar, aside	<aside>	<div class="sidebar"> → <aside>
section	<section>	<div class="section"> → <section>

Directory Structure

html-semantic-optimizer/
├── SKILL.md                    # 技能说明文档
├── requirements.txt            # 依赖列表
├── html_optimizer.py           # 核心模块（规则引擎 + DOM转换器）
├── example_rules.json          # 示例规则配置
└── scripts/
    ├── optimize.py             # 单个文件优化脚本
    └── batch_optimize.py       # 批量处理脚本

Configuration Rules

Default Rules

The script has 9 built-in default rules, covering common semantic scenarios.

Custom Rules

Create a JSON file to define custom rules (see example_rules.json）：

{
  "rules": [
    {
      "name": "侧边栏",
      "keywords": ["sidebar", "aside", "sidenav"],
      "target_tag": "aside",
      "priority": 8
    },
    {
      "name": "文章卡片",
      "keywords": ["card", "post-card"],
      "target_tag": "article",
      "priority": 7
    }
  ]
}

Rule Field Descriptions

Field	Type	Description
name	String	Rule identifier name
keywords	String array	List of matching keywords (regular expressions, case-insensitive)
target_tag	String	Target HTML tag
priority	Integer	Priority (the larger the value, the higher the priority)

Use the --rules parameter to load custom rules; rules with the same name will override the default rules.

Core Modules

RuleEngine (Rule Engine)

from html_optimizer import RuleEngine

engine = RuleEngine()
engine.load_from_file('rules.json')
rule = engine.find_matching_rule(['main-header', 'container'])

DOMTransformer (DOM Transformer)

from html_optimizer import RuleEngine, DOMTransformer

engine = RuleEngine(rules)
transformer = DOMTransformer(engine)
result = transformer.transform(html_content)

Automatic handling:

• Skip special tags such as <script>、<style>、<html>、<body> and other special tags
• Add <button> to type="button"
• Add <a> to href="#"
• Preserve all original attributes

Convenience Functions

from html_optimizer import optimize_html

# 一行代码完成优化
result = optimize_html(html_content)

Batch Processing

# 处理单个目录
python scripts/batch_optimize.py ./html_files/ -o ./optimized/

# 递归处理子目录
python scripts/batch_optimize.py ./html_files/ --recursive -o ./optimized/

# 并行处理（4个进程）
python scripts/batch_optimize.py ./html_files/ -o ./optimized/ --workers 4

# 试运行模式
python scripts/batch_optimize.py ./html_files/ -o ./optimized/ --dry-run

Notes

1. Back Up Original Files - Back up important files before conversion
2. Use Dry Run Mode - --dry-run Preview results without saving
3. Test Custom Rules - First verify the rule effects on a test file
4. Rule Priority - Higher-priority rules are matched first

Dependencies

• Python 3.6+
• beautifulsoup4 >= 4.9.0
• lxml >= 4.6.0

Install command:

pip install -r requirements.txt