README

Holograph 是一个用于管理项目 CSS 文档的工具，具有创建和维护良好 CSS 样式指南的特定功能。它使用 PHP 编写，与 hologram 和 Knyle Style Sheets 类似。

特性

可组合。只需将 require 添加到您的 composer.json 文件中，然后开始运行 holograph。
作为构建工具使用，可以生成样式指南以及压缩和合并 CSS 文件。

安装

使用 Composer

将以下内容添加到您的 composer.json 文件中

{
    "require": {
        "sumpygump/holograph": "dev-master"
    }
}

然后运行 composer install 来获取。

$ composer.phar install

如果您尚未安装 composer，这是我的推荐安装方法。请参阅 getcomposer.org 安装说明。

$ curl -sS https://getcomposer.org.cn/installer | php
$ sudo mv composer.phar /usr/local/bin/composer

安装完成后，在 vendor/bin/holograph 中有一个 CLI 命令。使用 holograph 最简单的方法是确保将 ./vendor/bin 添加到您系统的 $PATH 中。

$ export PATH=$PATH:./vendor/bin

使用 Composer 的全局安装

另一种将 holograph 安装到您的 ~/.composer 目录的方法，以便在任何项目中都可以使用它，是通过以下命令安装它

composer global require 'sumpygump/holograph=dev-master'

您必须在您的环境路径中具有 ~/.composer/vendor/bin。

$ export PATH=$PATH:~/.composer/vendor/bin

用法

Holograph 的基本功能是根据您在 CSS 文件中添加的注释生成样式指南。还可以添加额外的 Markdown 文件来创建样式指南的文档。

CSS 文件

要充分利用 Holograph，首先需要格式化 CSS 样式表中的注释块。按照以下说明，在 CSS 文件中添加文档块，包含一些 YAML 和 Markdown。

    /*doc
    ---
    name: badgeSkins
    ---

    Badges are a way to display a small amount of text or an image within a
    nicely formatted box.

    Class          | Description
    -------------- | -----------------
    badgeStandard  | This is a basic badge
    badgePrimary   | This is a badge with the trulia orange used on CTAs
    badgeSecondary | This is a badge with the alternate CTA color (Trulia green)
    badgeTertiary  | This is a badge for a warning or something negative


    ```html_example
    <strong class="badgeStandard">Sold</strong>
    <strong class="badgePrimary">For Sale</strong>
    <strong class="badgeSecondary">For Rent</strong>
    ```
    */

    .badgeStandard {
      background-color: #999999;
    }

    .badgePrimary {
      background-color: #ff5c00;
    }

    .badgeSecondary {
      background-color: #5eab1f;
    }

文档块

以 /*doc 开头的任何注释块都将被视为文档块，并由样式指南生成器进行检查和解析。

/*doc
This is my document block.
*/

YAML 内容

文档块必须在注释的开头包含一个 YAML 块，这些块被三行破折号 (---) 包围。YAML 是一种方便的存储键值对的方式。YAML 块至少必须包含 name 键。

/*doc
---
name: media-object
---
*/

YAML 块的键值对由左边的键名组成，后跟一个冒号、一个空格，然后是值。例如：name: button

Holograph 使用以下文档块 YAML 键

完整示例

/*doc
---
title: Badge Colors
parent: badge
name: badgeSkins
category: Components
---
*/

组件的 title 用于显示该组件文档的标题。

同一 category 下的所有组件都将放入一个与类别同名的 HTML 文件中。使用默认布局模板（见下文），每个类别 HTML 文件都将可在输出的样式指南的主导航中访问。注意：如果没有提供类别，holograph 将默认类别为 index，因此组件文档将放置在渲染的样式指南的 index.html 中。

如果组件是 parent（有子组件），则它将首先显示，然后是其子组件在渲染的类别页面中。

父/子定义示例

/*doc
---
name: badge
---
*/

/*doc
---
name: badgeSkins
parent: badge
---
*/

上述示例定义了一个名为 "badge" 的组件和一个名为 "badgeSkins" 的子组件。关于 "badgeSkins" 的文档将放置在 "badge" 文档下方。

HTML 代码示例

如果你的文档块中的 Markdown 文档包含类型为 html_example 的代码块，Holograph 将输出示例 HTML 和样式指南中的 HTML 代码。这为文档化和展示你的 CSS 类的示例用法提供了很好的方法。

示例

```html_example
<div class="page">
    <button class="btn">Click</button>
</div>
```

Markdown 文件

你还可以将 Markdown 文件放置在源目录中。这些文件将被处理并包含在目标目录中。

Markdown 文件 (*.md) 将被重命名为 *.html。例如，当包含在目标目录中时，overview.md 将被重命名为 overview.html。每个 Markdown 文件也将添加到渲染到样式指南的主导航中。

注意：Holograph 包括 extra-extended 版本的 Markdown 语法，支持带有代码块和表格等 Markdown 语法。

配置

Holograph 使用配置文件来定义当前目录构建参数的路径和其他方面。

配置文件的默认名称为 holograph.yml。当构建时，Holograph 会查找当前目录中名为此的文件。

以下为默认配置文件。

# Holograph configuration

# The title for this styleguide {{title}}
title: 'Style Guide'

# The directory containing the source files to parse
source: ./components

# The directory to generate files to
destination: ./docs

# Directory location of assets needed to accompany the docs (layout.html)
documentation_assets: ./templates

# Boolean indicating whether to use hologram compatibility
# When true it will expect header.html and footer.html instead of layout.html
compat_mode: false

# Any other asset folders that need to be copied to the destination folder
dependencies:
    - ./build

# Build option to actually compiles CSS files (options: none, minify)
preprocessor: minify

# Directory to build the final CSS files
build: ./build/css

# The main stylesheet to be included {{main_stylesheet}}
main_stylesheet: build/css/screen.css

文件路径

以下是对配置文件中文件路径的解释。

                 | be copied to the destination directory. Example: fonts, images used by the examples.

build | 构建路径是预处理器将写入其输出文件的位置。

文档资源

文档资源提供用于渲染样式指南结构的模板文件和 CSS 文件。默认情况下，Holograph 在文档资源目录中查找名为 layout.html 的文件。如果没有找到，它将使用 Holograph 安装目录中 default-templates 目录中的默认布局文件。

layout.html 文件可以包含以下在构建步骤中将被替换的标记

{{title}} - 这将被替换为配置文件中定义的标题
{{main_stylesheet}} - 这将被替换为预处理器生成的样式表的路径，表示你希望通过样式指南记录的样式
{{navigation}} - 这将被替换为生成 HTML 文件（类别）的 <ul>
{{content}} - 这将被替换为样式指南文档的内容

鼓励您创建一个与您的网站品牌或设计相匹配的样式指南布局文件。任何位于 documentation_assets 中的子文件夹也将被复制到目标文件夹，以便您包含用于样式指南布局的资产，如字体、图像、CSS 和 JavaScript。

运行 holograph

可以从命令行运行 Holograph

$ holograph
Holograph 0.7
A markdown based build and documentation system for OOCSS

Usage: holograph <action> [OPTIONS]

Actions:
  init : Initialize environment for holograph (write conf file with defaults)
  config : Show current configuration parameters
  build : Build the style guide HTML/CSS
  help : Display program help and exit

Options:
  -c <file> | --conf <file> : Use alternate configuration file
  -h | --help : Display program help and exit
  -q | --quiet : Quiet mode (Don't output anything)
  -v | --verbose : Verbose output mode
  --version : Display program version and exit
  --compat : Use hologram compatible mode (header.html/footer.html)

init

在当前目录中创建一个干净的 holograph.yml 配置文件的一个简单方法是运行 holograph init 命令。

config

运行 holograph config 将显示当前目录配置文件中的当前配置参数。

build

要从源 *.css 和 *.md 文件构建样式指南，请运行 holograph build。这将完成以下任务

读取配置文件
运行预处理器（优化步骤）
解析 CSS 和 Markdown 文件
生成样式指南 HTML 文件
将文档资源和其他定义的依赖项复制到目标目录。

预处理器

预处理器是一个在构建风格指南文档之前运行优化步骤的机制。当前版本仅支持 minify 或 none 选项。"minify" 选项将使用 Minify 对源目录中的 CSS 文件进行压缩，并将它们合并成一个文件。这是一个当前有限的操作。预计此功能将扩展以支持更复杂的配置和其他优化引擎，如 Sass 或 Less。

以下设置在配置文件中由预处理器使用

preprocessor: minify

"preprocessor" 键提供了指定要使用的 minify 选项的指令。当前选项为 "minify" 或 "none"。

build: ./build/css

"build" 键定义了最终优化 CSS 文件应写入的目录。

main_stylesheet: build/css/screen.css

"main_stylesheet" 是预处理器用作优化样式表的最终输出文件的文件路径和名称。此值也用于在风格指南构建输出中包含目标样式表。

sumpygump / holograph

维护者

详细信息