🧠 Python SSG 思维导图架构

🎯 核心目标

构建轻量级、高效的Python静态站点生成器

  • 将Markdown内容转换为静态HTML
  • 支持模板系统和主题定制
  • 提供插件扩展机制
  • 优化构建性能和SEO

🏗️ 系统架构

1️⃣ 内容层 (Content Layer)

内容管理

  • 输入格式: Markdown (.md)
  • 元数据: YAML Frontmatter

  • 目录结构: 

    content/
├── posts/          # 博客文章
├── pages/          # 静态页面
├── docs/           # 文档
└── assets/         # 资源文件

  • Frontmatter示例: 

    ---
title: "文章标题"
date: 2025-09-08
tags: [python, ssg]
draft: false
---

2️⃣ 解析层 (Parser Layer)

内容解析

  • Markdown处理器:
  • 基础语法支持 (标题、段落、列表等)
  • 代码块语法高亮 (Pygments)
  • 数学公式 (MathJax支持)

  • 表格、脚注扩展

  • 元数据提取:

  • YAML Frontmatter解析
  • 自动生成摘要

  • 标签和分类提取

  • 链接处理:

  • 内部链接解析
  • 图片路径优化
  • 相对路径转换

3️⃣ 模板层 (Template Layer)

模板系统

  • 引擎: Jinja2
  • 模板类型:
  • base.html (基础模板)
  • post.html (文章模板)
  • page.html (页面模板)

  • list.html (列表模板)

  • 模板继承: 

    <!-- base.html -->
<!DOCTYPE html>
<html>
<head>
  <title>{% block title %}{{ title }}{% endblock %}</title>
  <meta name="description" content="{{ description }}">
</head>
<body>
  {% block content %}{% endblock %}
</body>
</html>

  • 变量注入:

  • {{ title }} - 页面标题
  • {{ content }} - 主要内容
  • {{ date }} - 发布日期
  • {{ tags }} - 标签列表

4️⃣ 生成层 (Generator Layer)

静态生成

  • 构建流程:
  • 扫描内容目录
  • 解析Markdown文件
  • 应用模板渲染
  • 生成HTML文件
  • 复制静态资源

  • 优化输出文件

  • 输出结构: 

    public/
├── index.html          # 首页
├── posts/              # 文章目录
│   ├── post-1.html
│   └── post-2.html
├── tags/               # 标签页面
├── assets/             # 静态资源
└── feed.xml            # RSS订阅

  • 性能优化:

  • 增量构建 (只重建修改的文件)
  • 并行处理多文件
  • 缓存机制
  • 文件压缩 (HTML/CSS/JS)

5️⃣ 插件层 (Plugin Layer)

扩展机制

  • 钩子系统:
  • pre_build: 构建前执行
  • post_parse: 解析后执行
  • pre_render: 渲染前执行

  • post_build: 构建后执行

  • 内置插件:

  • Sitemap生成器
  • RSS/Atom订阅
  • 图片压缩
  • SEO优化

  • 代码高亮

  • 自定义插件: 

    class CustomPlugin:
    def pre_render(self, context):
        # 自定义处理逻辑
        return context

6️⃣ 配置层 (Config Layer)

配置管理

  • 配置文件: config.yaml 

    site:
  title: "我的站点"
  description: "个人博客"
  url: "https://example.com"

build:
  output_dir: "public"
  theme: "default"
  plugins: ["sitemap", "rss"]

markdown:
  extensions: ["codehilite", "tables"]
  syntax_highlight: true

  • 环境变量: 支持开发/生产环境切换

  • 主题配置: 自定义颜色、字体、布局

工作流程

graph TD A[Markdown内容] --> B[Frontmatter解析] B --> C[Markdown转HTML] C --> D[模板渲染] D --> E[静态HTML生成] E --> F[资源复制] F --> G[输出目录] H[配置文件] --> D I[模板文件] --> D J[插件系统] --> E

🛠️ 技术栈

核心依赖

主要库

  • markdown: Markdown解析
  • PyYAML: YAML配置解析
  • Jinja2: 模板引擎
  • click: 命令行接口
  • watchdog: 文件监控
  • livereload: 热重载

可选扩展

增强功能

  • Pillow: 图片处理
  • beautifulsoup4: HTML解析
  • pygments: 代码高亮
  • lxml: XML处理 (RSS)
  • csscompressor: CSS压缩

📊 性能优化

构建优化

提速策略

  • 增量构建: 只处理修改的文件
  • 并行处理: 多线程/多进程
  • 缓存机制: 缓存解析结果
  • 内存优化: 流式处理大文件

输出优化

文件优化

  • HTML压缩: 移除空白字符
  • CSS压缩: 合并和压缩样式
  • JS压缩: 混淆和压缩脚本
  • 图片优化: 自动压缩图片

🔧 命令行接口

# 初始化项目
ssg init my-site

# 构建站点
ssg build [--watch] [--draft]

# 本地预览
ssg serve [--port 8000]

# 创建内容
ssg new post "文章标题"
ssg new page "页面标题"

# 清理构建
ssg clean

📁 项目结构

my-site/
├── content/          # 内容目录
│   ├── posts/        # 文章
│   ├── pages/        # 页面
│   └── assets/       # 资源
├── templates/        # 模板
│   ├── base.html
│   ├── post.html
│   └── page.html
├── static/           # 静态文件
│   ├── css/
│   ├── js/
│   └── images/
├── themes/           # 主题
├── plugins/          # 插件
├── config.yaml       # 配置文件
├── public/           # 输出目录 (自动生成)
└── ssg.py           # 主程序

🚀 部署方案

静态托管

支持平台

  • GitHub Pages: 免费, 自动部署
  • Netlify: CDN, 表单处理
  • Vercel: 高性能, 边缘网络
  • Cloudflare Pages: 全球CDN
  • 阿里云OSS: 国内访问优化

CI/CD流程

# .github/workflows/deploy.yml
name: Deploy Site
on:
  push:
    branches: [ main ]
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Set up Python
      uses: actions/setup-python@v2
      with:
        python-version: '3.9'
    - name: Install dependencies
      run: pip install -r requirements.txt
    - name: Build site
      run: python ssg.py build
    - name: Deploy to GitHub Pages
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./public

🔍 SEO优化

元数据优化

SEO功能

  • 自动生成: 标题、描述、关键词
  • OpenGraph: 社交媒体分享优化
  • 结构化数据: JSON-LD格式
  • XML站点地图: 搜索引擎友好
  • RSS订阅: 内容同步

性能指标

Core Web Vitals

  • LCP (Largest Contentful Paint): < 2.5s
  • FID (First Input Delay): < 100ms
  • CLS (Cumulative Layout Shift): < 0.1
  • 移动端优化: 响应式设计
  • PWA支持: 离线访问

这个思维导图方案提供了一个完整的Python SSG实现思路，涵盖了从内容管理到部署优化的全流程。您可以根据具体需求选择实现其中的部分或全部功能。

字段 作用 缺省回退
title 文章页 <title> 与 <h1> 文件名
date 首页排序、日期显示 None（放最后）
summary 首页卡片摘要 title
tags 首页标签云、单页标签块 空列表
slug 自定义 URL（预留） 文件 stem
author 文章页作者 不显示
cover 封面图（预留） 无
draft: true 设为草稿，首页/列表不展示 false