Complexity项目高级使用指南：构建专业静态网站

项目结构深度解析

Complexity作为一个静态网站生成工具，其高级使用方式展现了强大的灵活性。让我们从一个典型的高级项目结构开始：

my_project/
├── project/       # 输入目录
│   ├── assets/    # 静态资源
│   │   ├── css/   # 样式表
│   │   ├── js/    # JavaScript文件
│   │   ├── img/   # 图片资源
│   │   ├── ico/   # 图标文件
│   │   └── robots.txt # 搜索引擎配置文件
│   ├── context/   # 数据上下文
│   │   ├── books.json # 书籍数据
│   │   └── movies.json # 电影数据
│   ├── templates/ # 模板文件
│   │   ├── base.html # 基础模板
│   │   ├── index.html # 首页模板
│   │   └── about.html # 关于页面模板
│   └── complexity.yml # 配置文件
│
└── www/           # 输出目录
    ├── index.html # 生成的首页
    ├── about/
    │   └── index.html # 生成的关于页面
    ├── css/      # 生成的CSS目录
    ├── js/       # 生成的JS目录
    ├── img/      # 生成的图片目录
    └── ico/      # 生成的图标目录

这种结构清晰地分离了开发环境和生产环境，使得项目管理更加规范。

深度配置complexity.yml

complexity.yml是Complexity项目的核心配置文件，它提供了细粒度的控制选项：

# Complexity项目配置文件示例

# 目录配置（相对于当前项目目录）
templates_dir: "templates"  # 模板目录
assets_dir: "assets"       # 静态资源目录
context_dir: "context"     # 数据上下文目录
output_dir: "../www"       # 输出目录

# 不需要扩展URL的模板列表
unexpanded_templates:
 - "404.html"              # 404错误页面
 - "500.html"              # 500错误页面

配置项详解

1. 目录配置：

   • templates_dir：存放所有需要被渲染的模板文件
   • assets_dir：存放静态资源，这些文件会被直接复制到输出目录
   • context_dir：存放JSON格式的数据文件，这些数据会自动注入模板上下文
   • output_dir：生成的网站输出目录

2. 特殊配置：

   • unexpanded_templates：指定哪些模板不需要生成"漂亮"的URL格式。默认情况下，Complexity会将about.html转换为about/index.html，但对于错误页面，我们通常希望保持原始文件名。

默认配置

如果不提供complexity.yml文件，Complexity会使用以下默认配置：

templates_dir: "templates"
assets_dir: "assets"
context_dir: "context"
output_dir: "../www"

数据驱动模板：JSON自动加载

Complexity的一个强大特性是它能自动将JSON文件转换为模板可用的上下文数据。

实际应用示例

假设我们有一个书籍数据文件context/books.json：

[
  {
    "url": "http://www.amazon.com/Two-Scoops-Django-Best-Practices/dp/1481879707/",
    "title": "Two Scoops of Django"
  },
  {
    "url": "http://www.amazon.com/Very-Magical-Caterpillar-Tale-Butterfly/dp/1453714081/",
    "title": "A Very Magical Caterpillar Tale"
  }
]

在模板中，我们可以直接使用这些数据：

{% extends 'base.html' %}

{% block title %}我的书籍{% endblock %}

{% block content %}
    <h2>我的藏书</h2>
    <ul class="book-list">
        {% for book in books %}
            <li>
                <a href="{{ book.url }}" target="_blank">{{ book.title }}</a>
            </li>
        {% endfor %}
    </ul>
{% endblock %}

工作机制解析

1. Complexity会自动扫描context_dir目录下的所有.json文件
2. 每个JSON文件会被解析并注入模板上下文
3. 文件名（不含扩展名）会成为模板中的变量名
4. 数据可以在模板中直接访问和迭代

静态JSON文件处理

如果需要将JSON文件作为静态资源而非模板数据，只需将其放在assets/目录下的任意位置（如assets/js/）。这些文件会被原样复制到输出目录，不会进行模板处理。

静态资源管理

Complexity对静态资源的管理非常灵活：

1. 资源目录：可以在assets/下创建任意类型的子目录结构
2. 文件类型：支持所有类型的静态文件（CSS、JS、图片、字体等）
3. 处理流程：所有资源都会被原样复制到输出目录

专业提示：虽然当前版本主要进行简单的文件复制，但未来版本计划加入更多高级功能，如CSS/JS压缩、图片优化、SASS/LESS编译等预处理功能。

编程式API使用

Complexity不仅可以作为命令行工具使用，还可以作为Python库集成到其他项目中。

基础使用示例

from complexity.main import complexity

# 最简单的调用方式
complexity('project/', 'www/')

高级API调用

from complexity import generate

# 生成上下文数据
context = generate.generate_context(context_dir='project/context/')

# 渲染模板
generate.generate_html(
    templates_dir='project/templates/',
    output_dir='www/',
    context=context
)

# 复制静态资源
generate.copy_assets(
    assets_dir='project/assets/',
    output_dir='www/'
)

集成建议

1. 依赖管理：由于API可能发生变化，建议固定Complexity的版本号
2. 自定义扩展：可以在调用API前后添加自己的处理逻辑
3. 错误处理：适当添加异常处理以增强健壮性

最佳实践建议

1. 项目结构：保持清晰的目录结构，便于维护
2. 配置管理：即使是小型项目也建议使用complexity.yml
3. 数据分离：将可变内容放在JSON文件中，便于维护和更新
4. 模板复用：充分利用模板继承减少重复代码
5. 版本控制：建议将project/目录纳入版本控制，而www/目录可以忽略

通过掌握这些高级用法，你可以充分发挥Complexity的潜力，构建出结构清晰、易于维护的专业静态网站。