Highlight 项目技术文档

1. 安装指南

1.1 安装 Highlight Gem

Highlight 是一个用于 Ruby 和 Rails 的简单语法高亮 gem。安装步骤如下：

gem install highlight

1.2 在 Rails 项目中使用 Highlight

在 Rails 项目中使用 Highlight，需要在 Gemfile 中添加依赖：

gem 'highlight', :require => 'simplabs/highlight'

1.3 安装 Pygments

Highlight 依赖于 Pygments 进行语法高亮。如果您的机器上没有安装 Pygments，请参考 Pygments 安装指南 进行安装。

1.4 生成默认 CSS 文件

Highlight 提供了一个默认的 CSS 文件，用于定义高亮代码的样式。可以通过以下命令将该 CSS 文件复制到 Rails 应用的 public/stylesheets 目录：

./bin/rails generate highlight_styles

2. 项目使用说明

2.1 独立使用

Highlight 可以独立使用，通过以下方式引入并调用：

require 'simplabs/highlight'
Simplabs::Highlight.highlight(:ruby, 'class Test; end')

2.2 在 Rails 中使用

在 Rails 中，Highlight 提供了 highlight_code 辅助方法，可以在视图中使用：

highlight_code(language, code = nil, &block)

其中 language 可以是符号或字符串，表示代码的语言类型。代码可以通过字符串或块的形式传递，例如：

highlight_code(:ruby, 'class Test; end')

或者：

highlight_code(:ruby) do
  klass = 'class'
  name  = 'Test'
  _end  = 'end'
  "#{klass} #{name}; #{_end}"
end

2.3 缓存高亮代码

由于代码高亮过程较慢，建议将高亮后的代码进行缓存，例如：

<%- code = 'class Test; end' -%>
<%- cache Digest::SHA1.hexdigest(code) do -%>
  <%= highlight_code(:ruby, code) -%>
<%- end -%>

3. 项目 API 使用文档

3.1 highlight_code 方法

highlight_code 方法用于在 Rails 视图中高亮代码。其参数如下：

• language: 代码的语言类型，可以是符号或字符串。
• code: 要高亮的代码，可以是字符串或通过块传递。

3.2 Simplabs::Highlight.highlight 方法

Simplabs::Highlight.highlight 方法用于独立使用 Highlight 进行代码高亮。其参数如下：

• language: 代码的语言类型，可以是符号或字符串。
• code: 要高亮的代码，必须是字符串。

4. 项目安装方式

4.1 通过 Gem 安装

gem install highlight

4.2 在 Rails 项目中添加依赖

在 Gemfile 中添加：

gem 'highlight', :require => 'simplabs/highlight'

4.3 安装 Pygments

如果您的机器上没有安装 Pygments，请参考 Pygments 安装指南 进行安装。

4.4 生成默认 CSS 文件

./bin/rails generate highlight_styles

通过以上步骤，您可以成功安装并使用 Highlight 项目。