Brix — UX

demo 与文档

Brix Style 是指 Brix 框架中基础样式的部分，使用 Less 编写，部分组件依赖 Brix 的 JS 部分以初始化（例如 Forms）。

文档都在 gh-pages-source 分支，不妨先看一下该分支的 README。

编写组件时，通常都需要一份演示 HTML，而在给其他人用的时候，在过往，我们也都是直接给 demo 即可。但是 Brix 的受众不限于前端工程师，后端开发人员也需要了解、使用。因此，一个良好的组件，应该提供 两份文件。以 grid 举例：

demo：demo/style/grid-fixed.html
post：style/_posts/2012-07-13-grid.html

demo

demo 用来测试样式，实现功能，穷举一些边界情况。为了避免依赖 jekyll，方便组件开发（jekyll 环境在 Windows 下不好弄），它是静态文件，存放于 demo/style/ 目录下。

因此，有几点需要注意：

demo 中不应包含代码片段；
demo 中不应包含组件使用方式说明；
demo 中不需要过多的组件外样式。

代码片段、使用方式说明，应该写到文档中去。

文档

而文档应当是个简化的东东，告诉别人如果要用你的样式，你的 HTML 应该怎么写。如果 HTML 结构看起来有点怪，不妨在文档中解释，为什么你的实现方式是如此，可以省却许多口水。

如何写文档

格式

文档的格式可以由组件开发者自行决定，可以选择直接写 HTML，或者 Markdown，甚至是 Textile。这是 Brix 网站所采用的网站生成工具 jekyll 提供的功能，一篇文章，会以文件扩展名决定其格式。再以 grid 为例，2012-07-13-grid.html 是这篇文档的文件名，以 <创建日期>-<标题>.<格式> 组成。所以，这是一篇创建于今年7月13日的一篇 HTML 格式的文档。

目前，Brix Style 的文档，推荐使用以下两种格式之一：

md ==> Markdown
html ==> HTML

头部 YAML

在 style/_posts 目录下的每篇文档，头部都有这种信息：

---
title: Grid
demo: grid-fixed
layout: style
---

它的格式是 YAML，YAML Ain't Markup Language，在 jekyll 中叫做 YAML Front Matter，用来给文章添加定制信息。诸位在新建文档时，只要拷过去，修改相应的内容就可以了，请勿增删属性。

title：即文章标题，用于在页面中显示，区别于前面说到的文件名中的“标题”，比如 grid 与 Grid；
demo：组件演示文件的实际名称，建议与文档文件名一致，例如，demo: grid-fixed，在使用时会替入 <a href="/brix/demo/style/<demo>.html">demo</a>，变成 <a href="/brix/demo/style/grid-fixed.html">demo</a>；

layout 是单独渲染此页面时所使用的模板文件，style/_posts 下的都是 style，即 _layouts/style.html 模板文件，请勿修改。

内容中插入 Liquid Template

在文档中，除了你所选择的格式的写法之外，还支持使用 Liquid 模板的语法，例如，在 2012-04-10-hello.md 中，我们可以这么写：

[{{ 'brix' | capitailize }}](http://etaoux.github.com/brix) is awesome!

这里的解析顺序是这样的：

把内容交给 Liquid 引擎，Brix 变成了 Brix
[Brix](http://etaoux.github.com/brix) 再交给 Markdown 引擎，变成最终我们想要的 <a href="http://etaoux.github.com/brix">Brix</a>

不过，通常我们写文档时需要用的标签只有两个，highlight 和 demo。

使用 highlight 高亮代码

{% highlight c %}
#include <stdio.h>

int main() {
    printf("%s", "hello world\n");
}
{% endhighlight %}

结果如下：

#include <stdio.h>

int main() {
    printf("%s", "hello world\n");
}

引入 demo

指定 demo 目录下对应的文件名称即可，如下：

{{ demo 'style/grid-fixed.html' }}

将会生成：

<div class="demo">
  <iframe src="/brix/demo/style/grid-fixed.html" frameborder="0" scrolling="0" class="j-demo"></iframe>
</div>

同时，demo 标签还支持简写：

{{ demo 'style/breadcrumb' }}