Stasis 静态站点动态框架技术文档

1. 安装指南

Stasis 是一个用于生成静态站点的动态框架，支持多种模板引擎。以下是安装 Stasis 的步骤：

通过 RubyGems 安装

Stasis 可以通过 RubyGems 进行安装。确保你已经安装了 Ruby 和 RubyGems，然后在终端中运行以下命令：

$ gem install stasis

安装完成后，你就可以在项目中使用 Stasis 了。

2. 项目的使用说明

基本使用

Stasis 的核心功能是将一个包含模板文件的目录树渲染为静态文件。假设你有一个如下的项目目录结构：

project/
    index.html.haml
    images/
        image.png

在项目根目录下运行 stasis 命令：

$ cd project
$ stasis

Stasis 会生成一个 public 目录，并将模板文件渲染为静态文件：

project/
    index.html.haml
    images/
        image.png
    public/
        index.html
        images/
            image.png

开发模式

在开发过程中，你可以使用 -d 参数启动开发模式，Stasis 会在文件保存时自动重新生成静态文件：

$ stasis -d

你还可以指定一个端口启动 HTTP 服务器：

$ stasis -d 3000

指定输出文件或目录

你可以通过 -o 参数指定只渲染特定的文件或目录：

$ stasis -o index.html.haml,subdirectory

更改输出目录

通过 -p 参数可以更改生成的静态文件的输出目录：

$ stasis -p ../public

3. 项目 API 使用文档

控制器

控制器包含在模板渲染之前执行的 Ruby 代码。你可以在任何目录层级中添加控制器文件 controller.rb。

before 块

在 controller.rb 中使用 before 块可以在模板渲染之前执行代码：

before 'index.html.haml' do
  @something = true
end

@something 变量现在可以在 index.html.haml 模板中使用。

layout 方法

你可以通过 layout 方法设置默认布局或为特定模板设置布局：

layout 'layout.html.haml'

或者为特定模板设置布局：

layout 'index.html.haml' => 'layout.html.haml'

render 方法

在模板中使用 render 方法可以渲染局部模板：

%html
  %body= render '_partial.html.haml'

在 before 块中也可以使用 render 方法：

before 'index.html.haml' do
  @partial = render '_partial.html.haml'
end

instead 方法

instead 方法可以改变模板的输出：

before 'index.html.haml' do
  instead render('subdirectory/index.html.haml')
end

helpers 方法

通过 helpers 方法可以定义辅助方法，这些方法可以在所有 before 块和模板中使用：

helpers do
  def say_hello
    'Hello'
  end
end

ignore 方法

使用 ignore 方法可以忽略某些路径：

ignore /\/_.*/

priority 方法

通过 priority 方法可以改变文件的处理顺序：

priority /.*txt/ => 2, 'index.html.erb' => 1

4. 项目安装方式

Ruby 库方式

除了命令行工具，Stasis 还可以作为 Ruby 库使用。你可以通过以下方式实例化 Stasis 对象：

stasis = Stasis.new('/path/to/project/root')

你可以指定输出目录：

stasis = Stasis.new('/project', '/html')

渲染所有模板：

stasis.render

渲染特定模板或目录：

stasis.render('index.html.haml', 'subdirectory')

支持的模板引擎

Stasis 使用 Tilt 支持多种模板引擎，包括但不限于：

• ERB
• Haml
• Sass
• Less CSS
• Markdown
• CoffeeScript

完整的支持列表可以在项目的 README 文件中找到。

总结

Stasis 是一个功能强大的静态站点生成框架，支持多种模板引擎和灵活的控制器机制。通过本文档，你可以快速上手 Stasis，并利用其丰富的功能来构建高效的静态站点。