Ruby Stylus 技术文档

本文档将详细介绍如何安装、使用 Ruby Stylus 项目，以及如何使用其 API。以下是项目的主要组成部分：

1. 安装指南

首先，确保您的系统已安装 Node.js。以下是 Ruby Stylus 的安装方法：

• 如果您有 Gemfile，请添加以下代码：

  gem 'stylus'
  

• 或者，直接在系统中安装：

  gem install stylus
  

ruby-stylus-source 包含 Stylus 源码，作为本项目的依赖项一同安装。ruby-stylus-source 的版本与 Stylus 版本保持一致。

请注意，您仍需要在运行环境中提供 node 命令。本项目还兼容 Heroku Cedar 环境，可以在应用部署期间编译资源。

2. 项目使用说明

Ruby Stylus 通过 Stylus 模块进行交互，您可以编译 Stylus 语法到 CSS，将 CSS 转换回 Stylus，启用插件，以及其他选项：

require 'stylus'

# 接受原始字符串或 IO 对象（如 File、StringIO 或任何响应 'read' 方法的对象）。
Stylus.compile(File.new('application.styl')) # 返回编译后的样式表。

# 使用 :compress 选项，从代码中删除大多数换行符。
Stylus.compile(File.read('application.styl'), compress: true)

# 或者设置全局压缩标志
Stylus.compress = true
Stylus.compile(File.read('application.styl'))

# 将过时的 CSS 转换为出色的 Stylus。
Stylus.convert(File.new('file.css'))

# 直接从 Node.js 导入插件，如 nib。
Stylus.use :nib

# 启用调试信息，将 'linenos' 和 'firebug' 选项发送到 Stylus。
# 如果您向 `Stylus.compile` 方法提供原始内容字符串，请记住发送一个 `:filename` 选项，
# 以便 Stylus 可以定位您的样式表进行正确的检查。
Stylus.debug = true

在 Rails 和资产管道中使用的说明

将 stylus 添加到您的 Gemfile 中后，您可以使用 Rails 3.1 管道处理 .styl 文件。使用 rails generate 生成的任何资源都将具有 .css.styl 扩展名。

任何 @import 指令都将添加样式表作为 sprockets 依赖项，因此当您更新外部库时，它将反映在您的资源指纹上。此外，sprockets 载入路径（通常是 app/assets、lib/assets、vendor/assets 和任何其他 gem 内的 assets 文件夹）将可用于您的样式表。

如果 config.assets.debug 被打开，Stylus 将在您的样式表中输出额外的注释以帮助调试和检查，使用 linenos 和 firebug 选项。查看 FireStylus Firebug 扩展 了解更多信息。

请注意，在默认的 Rails 项目中，您应该删除 sass-rails gem。这个 gem 包括了 tilt gem，这是资产管道所需的，因此您也应该单独添加这个 gem。

# gem 'sass-rails'
gem 'tilt'

对于在部署期间（例如 Heroku）编译资源，您还需要启用/添加 rubyracer gem。

# 请查阅 https://github.com/rails/execjs#readme 了解更多支持的运行时
gem 'therubyracer', platforms: :ruby

3. 项目 API 使用文档

以下是 Ruby Stylus 的一些主要 API 方法：

• Stylus.compile(file_or_string, options = {}): 编译 Stylus 语法到 CSS。
• Stylus.convert(file_or_string): 将 CSS 转换为 Stylus 语法。
• Stylus.use(plugin): 使用 Node.js 编写的插件。

更多 API 文档和示例，请参考项目仓库。

4. 项目安装方式

请遵循以下步骤以在您的项目中安装 Ruby Stylus：

1. 添加 gem 'stylus' 到您的 Gemfile。
2. 运行 bundle install 命令以安装依赖项。
3. 按照使用说明配置并使用 Ruby Stylus。

确保您的项目环境已正确设置，以便顺利使用 Ruby Stylus。