簡介支持多個主題並輸出可以由任何網站主機提供的HTML的 API Blueprint插件。 API藍圖是基於簡化的文檔格式，允許你以簡單簡單的方式編寫API描述和文檔。 目前支持的是 API Blueprint格式 1A 。

特性

• 快速解析感謝主角
• Asyncronous處理
• 多個模板/主題
• 支持自定義顏色，模板和主題引擎
• 在藍圖中包含其他文檔
• 命令行可執行文件 aglio -i service.apib -o api.html
• 實時重新載入預覽伺服器 aglio -i service.apib --server
• Node.js 庫 require(\'aglio\')
• 出色的測試覆蓋率
• 在 BrowserStack 測試

示例輸出

示例輸出是由示例 API ( 使用預設的Olio主題生成的) 。

• 默認主題兩列或者三列
• 條紋主題兩個列或者三列
• Flatly主題兩個列或者三列
• 板岩主題兩個列或者三列
• 機器人主題兩個列或者三列。

包含文件

通過使用特殊的包含指令和路徑到文件的當前目錄，可以在藍圖中包含其他的文件。 包含的文件可以寫在API藍圖，Markdown 或者 HTML ( 。響應示例的JSON ) 。 包含的文件可以包含其他文件，因此要小心循環引用。

<!-- include(filename.md) -->

對於不支持這裡工具的工具，它將只呈現為一個HTML註釋。 在以後的版本中，API Blueprint可能支持它自己的機制，而這個語法被選擇不干擾外部文檔的建議，同時允許用戶包含文件。
安裝&用法使用aglio有三種方法： 作為可執行文件，在 Docker 容器中或者作為 Node.js.的庫

可執行文件

通過NPM安裝aglio你需要安裝 node.js，並且你可能需要使用 sudo 來全局安裝：

npm install -g aglio

然後，開始生成 HTML 。

# Default themeaglio -i input.apib -o output.html# Use three-column layoutaglio -i input.apib --theme-template triple -o output.html# Built-in color schemeaglio --theme-variables slate -i input.apib -o output.html# Customize a built-in styleaglio --theme-style default --theme-style./my-style.less -i input.apib -o output.html# Custom layout templateaglio --theme-template/path/to/template.jade -i input.apib -o output.html# Custom theme engineaglio -t my-engine -i input.apib -o output.html# Run a live preview server on http://localhost:3000/aglio -i input.apib -s# Print output to terminal (useful for piping)aglio -i input.apib -o -# Disable condensing navigation linksaglio --no-theme-condense -i input.apib -o output.html# Render full-width page instead of fixed max widthaglio --theme-full-width -i input.apib -o output.html# Set an explicit file include path and read from stdinaglio --include-path/path/to/includes -i - -o output.html# Output verbose error information with stack tracesaglio -i input.apib -o output.html --verbose

帶 Docker的

你可以選擇使用提供的Dockerfile 來構建可以重複和可以測試的環境：

• 生成映像 docker build -t aglio.
• 在一個容器中運行 aglio inside docker run -t aglio 可以使用 -v switch 動態掛載保存你的API藍圖的文件夾：

docker run -v $(pwd):/tmp -t aglio -i/tmp/input.apib -o/tmp/output.html

node.js-庫

你也可以將aglio用作庫。 首先，安裝並將它的保存為一個依賴項：

npm install --save aglio

然後，將一些API藍圖轉換為 HTML:

var aglio =require(\'aglio\');// Render a blueprint with a template by namevar blueprint =\'# Some API Blueprint string\';var options = {
 themeVariables:\'default\'};aglio.render(blueprint, options, function (err, html, warnings) {
 if (err) returnconsole.log(err);
 if (warnings) console.log(warnings);
 console.log(html);
});// Render a blueprint with a custom template fileoptions = {
 themeTemplate:\'/path/to/my-template.jade\'};aglio.render(blueprint, options, function (err, html, warnings) {
 if (err) returnconsole.log(err);
 if (warnings) console.log(warnings);
 console.log(html);
});// Pass custom locals along to the template, for example// the following gives templates access to lodash and asyncoptions = {
 themeTemplate:\'/path/to/my-template.jade\',
 locals: {
 _:require(\'lodash\'),
 async:require(\'async\')
 }
};aglio.render(blueprint, options, function (err, html, warnings) {
 if (err) returnconsole.log(err);
 if (warnings) console.log(warnings);
 console.log(html);
});

引用

可以從 aglio 庫獲得以下方法：
aglio.collectPathsSync ( blueprint，includePath )獲取藍圖中包含的路徑列表。 這個列表可以被監視以做諸如實時重新載入之類的事情。 未包含自己的blueprint路徑。

var blueprint =\'# GET/foonn\';var watchPaths =aglio.collectPathsSync(blueprint, process.cwd())

aglio.render ( blueprint，選項，回調)呈現一個 API Blueprint字元串並將生成的HTML傳遞給回調。 options 可以是選項對象，也可以是簡單布局 NAME 或者文件路徑字元串。 可用選項包括：

選項類型默認說明

另外，默認主題插件提供了以下選項：

選項類型默認說明

var blueprint =\'...\';var options = {
 themeTemplate:\'default\',
 locals: {
 myVariable:125 }
};aglio.render(blueprint, options, function (err, html, warnings) {
 if (err) returnconsole.log(err);
 console.log(html);
});

aglio.renderFile ( inputFile，outputFile，選項，回調)

呈現一個 API Blueprint文件並將該HTML保存到另一個文件。 輸入/輸出文件參數是文件路徑。 除了默認為輸入文件名的basename 以外，選項的行為與 aglio.render的行為相同。

aglio.renderFile(\'/tmp/input.apib\', \'/tmp/output.html\', options, function (err, warnings) {
 if (err) returnconsole.log(err);
 if (warnings) console.log(warnings);
});

插件開發鼓勵請求請求歡迎 fork 和 hack 離開，特別是在新主題上。 正在使用的生成系統是Grunt的，因此請確保已經安裝該系統：

npm install -g grunt-cli

然後你可以構建源代碼並運行測試：

# Lint/compile the Coffeescriptgrunt# Run the test suitegrunt test# Generate an HTML test coverage reportgrunt coverage# Render examplesgrunt examples

定製輸出

Aglio分為兩個組件： 一個包含載入API藍圖。處理命令行參數等的基礎，以及處理將 API Blueprint AST轉換為HTML的主題引擎的一個。 Aglio的默認主題引擎是調用 olio 。 模板用 Jade 編寫，支持 inline 。LESS 和通過過濾器的手寫筆。 默認樣式表是用較少的。

你可能希望使用 NOCACHE 環境變數禁用緩存，但在開發定製時。

NOCACHE=1 aglio -i input.apib [customization options]

自定義顏色&樣式

默認的aglio主題提供了一種方法來輕鬆覆蓋顏色，字體，padding 等，以使你的公司風格。 通過使用 --theme-variables 和 --theme-style 選項提供你自己的LESS 或者CSS文件，這是。 例如：

# Use my custom colorsaglio --theme-variables/path/to/my-colors.less -i input.apib -o output.html

my-variables.less 文件可能包含自定義的HTTP放置顏色規範：

/* HTTP PUT */@put-color: #f0ad4e;@put-background-color: #fcf8e3;@put-text-color: contrast(@put-background-color);@put-border-color: darken(spin(@put-background-color, -10), 5%);

有關可以設置哪些變數的示例，請參見默認變數文件。

使用 --theme-style 選項可以使用你自己的LESS 或者CSS定義覆蓋內置的樣式。 變數在之後經過了處理，因此變數可以用於你的使用。 如果要修改現有內置樣式中的規則，則必須複製樣式。 載入的順序大致如下：

• 默認變數
• 內置或者用戶提供的變數
• 內置的或者用戶提供的樣式

注意，這些選項可以多次傳遞，在這種情況下，它們將按照傳遞的順序進行載入。 例如，可以以使用 flatly 載入一個變數預設，並用自己的LESS 文件修改一個顏色。 記住，當你想要修改內置樣式時，你必須顯式地列出樣式，比如 --theme-style default --theme-style my-style.less

內置顏色的

• cyborg
• default
• flatly
• slate

內置樣式

• default

自定義布局模板

使用 --theme-template 選項可以提供覆蓋默認布局模板的自定義布局模板。 這是以 Jade 模板文件的形式指定的。 有關示例，請參見默認模板文件。

模板可以用於模板的外觀如下所示：

名稱 描述

內置的布局模板

• default

使用自定義主題

儘管Aglio附帶了默認主題，但你可以選擇安裝和使用第三方主題引擎。 它們可以使用任何技術，並且不限於 Jade 和 LESS 。 查看主題文檔以查看哪些選項可用以及如何使用和自定義主題。 所有主題之間的常見用法：

# Install a custom theme engine globallynpm install -g aglio-theme-<NAME># Render using a custom theme engineaglio -t <NAME> -i input.apib -o output.html# Get a list of all options for a themeaglio -t <NAME> --help

編寫主題引擎

主題引擎只是提供兩個 public 函數並遵循特定命名方案( aglio-theme-NAME )的node.js 模塊。 因為它們是自己的npm包，所以它們可以使用主題引擎作者希望使用的任何技術。 唯一的困難要求是提供這兩個 public 函數：
getConfig()返回主題的配置信息，如支持的API Blueprint格式和主題提供的任何選項。
render(input, options, done)用給定的選項呈現給定的輸入API藍圖 AST 。 在完成時調用 done(err, html)，或者將錯誤或者呈現的HTML輸出作為字元串傳遞。
示例主題下面是一個非常簡單的示例主題。 英鎊註釋：它只返回一個非常簡單的字元串，而不是輸出API藍圖。 通常你會調用模板引擎並輸出生成的生成的HTML 。

// Get the theme\'s configuration optionsexports.getConfig=function () {
 return {
 // This is a list of all supported API Blueprint format versions formats: [\'1A\'],
 // This is a list of all options your theme accepts. See// here for more: https://github.com/bcoe/yargs#readme// Note: These get prefixed with `theme` when you access// them in the options object later! options: [
 {
 name:\'name\',
 description:\'Your name\',
 default:\'world\' }
 ]
 };
}// Asyncronously render out a stringexports.render=function (input, options, done) {
 // Normally you would use some template engine here.// To keep this code really simple, we just print// out a string and ignore the API Blueprint.done(null, \'Hello, \'+options.themeName+\'!\');
};

示例用法：

# Install the theme globallynpm install -g aglio-theme-hello# Render some output!aglio -t hello -i example.apib -o -
=>\'Hello, world!\'# Pass in the custom theme option!aglio -t hello --theme-name Daniel -i example.apib -o -
=>\'Hello, Daniel!\'

你可以隨意使用任何模板系統( Jade，EJS，Nunjucks等) 和任何支持庫( 比如 。 對於 CSS，你喜歡。
許可證版權所有( c ) 2016 Daniel G 。 泰勒

http://dgt.mit-license.org/