@aconex/styleguide 中文文档教程

Question

Aconex Styleguide

样式指南作为 UI 库的 npm 依赖项安装。

Starter template

使用入门模板了解配置和使用样式指南的基本项目设置：https://github.com/Aconex/样式指南启动器。

Working with your UI library

1. Install styleguide as a dependency in your project.

  npm install --save @aconex/styleguide

2. 配置样式指南的选项：

   从 UI 库的 package.json 配置样式指南的页面和导航标题。 例如：

  {
    "name": "ui-library",
    "version": "1.0.0",
    "styleguide": {
      "title": "My styleguide"
    }
  }

然后在启动样式指南之前提供您的 UI 库的路径和演示路由：

  const styleguide = require( '@aconex/styleguide' );

  styleguide
    .config( {
      uiLibrary: './path/to/ui-library',
      demos: function(expressApp, express) {
        // ...
      }
    } )
    .start();

• uiLibrary：指向您的 UI 库的路径。

• demos：为样式指南配置自定义路由的函数。 它将与样式指南的 express 实例和 express 本身一起调用。

  至少，应该配置 /demo 路由。 有关示例配置，请参阅 styleguide 中的 index.js -启动器。 在此示例中，/static 路由被配置为提供静态 CSS 和 JS 文件，而 /demo 路由为给定的演示文件呈现把手模板。

  然后在浏览器中浏览到 http://localhost:3080 以查看样式指南。

1. 创建样式指南内容。

   组件的文档写在 guide.md 文件中。 每个组件应该有一个指南文件。

   要生成样式指南的导航，它会查找 navigation.guide.json 文件。 以下面的文件夹和文件结构为例。

   Folder structure

  src
  |
  +-- components
  |    |
  |    +-- calendar
  |    |    |-- calendar.guide.md
  |    |    +-- calendar.demo.html
  |    |
  |    +-- datepicker
  |         |-- datepicker.guide.md
  |         +-- datepicker.demo.html
  |
  +-- navigation.guide.json

#### navigation.guide.json：

  {
    "sections": [
      {
        "title": "Components",
        "items": [
          { "title": "Calendar", "path": "components/calendar", keywords: "calendar date" },
          { "title": "Datepicker", "path": "components/datepicker", keywords: "datepicker date" }
        ]
      }
    ]
  }

在此示例中，导航菜单将包含一个组件部分，其中包含 2 个项目：日历和日期选择器。

keywords 属性是可选的，用于侧边栏的搜索。 如果提供，它应该包含一个以空格分隔的与该组件相关的关键字列表。

guide.md 文件的内容将在导航到特定组件时呈现。 在 guide.md 中，您可以嵌入 demo.html 的内容。

例如，导航到 components/calendar 将呈现 calendar.guide.md。 在 calendar.guide.md 中，您可以使用 --$ calendar.demo $-- 插入日历演示。

Publishing

样式指南公开了一个可执行文件 styleguide-publish 以简化发布到 RHCloud 的过程。 使用它的最简单方法是将脚本添加到 UI 库的 package.json。

此示例将从您的 UI 库的 src 文件夹中准备文件，以发布到名为 sg3 的 RHCloud 应用程序。 文件将输出到 publish 文件夹，准备推送到 RHCloud。

"scripts": {
  "publish": "styleguide-publish --app sg3 --ui-library ./src --output ./publish"
}

Contributing

请参阅 CONTRIBUTING.md。