Brochure 技术文档

1. 安装指南

首先，确保您的系统中已经安装了 Ruby 环境。接下来，通过以下命令安装 Brochure：

$ gem install brochure

Brochure 依赖于 Hike、Rack 和 Tilt，因此请确保这些库也已安装。

2. 项目使用说明

Brochure 是一个基于 Rack 的应用，用于提供静态网站服务，并支持 ERB 模板（或其他 Tilt 支持的模板语言）。以下是一个典型的应用结构示例：

templates/
  help/
    index.html.erb
  index.html.erb
  shared/
    _header.html.erb
    _footer.html.erb
  signup.html.erb
config.ru
public/
  ...

在 config.ru 文件中，您可以配置 Brochure：

require "brochure"
root = File.dirname(__FILE__)
run Brochure.app(root)

Brochure 会自动将 URL 映射到模板名称：

• / 映射到 templates/index.html.erb
• /signup 映射到 templates/signup.html.erb
• /help/ 映射到 templates/help/index.html.erb

3. 项目API使用文档

Partials 和 helpers

模板可以渲染 Partials。Partials 以下划线开头的文件名标识。例如，<%= render "shared/header" %> 会渲染 templates/shared/_header.html.erb。

Partials 可以通过 <%= yield %> 回到渲染它们的模板。这种方法可以用来将常见的头部和尾部标记提取到一个布局文件中。

模板可以通过 env 方法访问 Rack 环境，通过 application 方法访问 Brochure 应用程序。此外，还提供了一个围绕 Rack 环境的 Rack::Request 封装，可通过 request 方法访问。

您可以使用 h 辅助方法在模板中输出 HTML 转义字符串。

自定义辅助方法和实例变量

您可以将额外的辅助方法和实例变量添加到模板中。辅助方法位于 Ruby 模块中，可以通过 :helpers 选项包含到 Brochure.app 中：

module AssetHelper
  def asset_path(filename)
    local_path = File.join(application.asset_root, filename)
    digest = Digest::MD5.hexdigest(IO.read(local_path))
    "/#{filename}?#{digest}"
  end
end

run Brochure.app(root, :helpers => [AssetHelper])

类似地，实例变量可以通过 :assigns 选项定义：

run Brochure.app(root, :assigns => { :domain => "37signals.com" })

Tilt 模板选项

您可以为每个引擎指定全局 Tilt 模板选项，使用 :template_options：

run Brochure.app(root, :template_options => {
  ".haml" => { :format => :html5 },
  ".md"   => { :smart  => true }
})

4. 项目安装方式

请参考“安装指南”部分，使用 Ruby gem 命令安装 Brochure。