pug參考文檔

express框架的渲染模板有多種選擇，官方的例子是Pug，網上找了一下，Pug沒有可以參考的中文文檔，于是自己動手豐衣足食。翻譯水平一般，各位湊合著看吧。

1. API

ps：最近搜索了一下，中文文檔還是有的，不知道為啥當時死活百度上找不到。

https://pug.bootcss.com/api/getting-started.html

https://pugjs.org/zh-cn/api/reference.html

1.1 開始

安裝

通過npm安裝pug：

$ npm install pug

簡介

Pug的渲染語句很簡單，pug.compile()方法將pug源文件(.pug)源文件編譯成一個帶參數（‘locals’，pug文件的路徑）方法，然后調用這個結果方法就能購生成一段由pug文件轉化成的html字符串。

這個pug.compile()方法可以重復使用，生成各種各樣的html字符串來渲染html。

//- template.pug，pug文件
p #{name}'s Pug source code!

調用方法：

const pug = require('pug');

// 編譯pug源文件
const compiledFunction = pug.compileFile('template.pug');

// 渲染數據
console.log(compiledFunction({
  name: 'Timothy'
}));
// "<p>Timothy's Pug source code!</p>"

// 渲染另一個數據
console.log(compiledFunction({
  name: 'Forbes'
}));
// "<p>Forbes's Pug source code!</p>"

Pug還提供另外一種渲染方式：pug.render系列的方法，它把編譯和渲染合并成一個步驟，不需要生成編譯函數，直接渲染pug源文件。當然，默認情況下調用它每次都要編譯一次，這可能會影響性能。可以選擇配置項cache為true，將編譯函數緩存起來，不用每次都重新生成，編譯。如下面的pug.renderFile方式：

const pug = require('pug');

// Compile template.pug, and render a set of data
console.log(pug.renderFile('template.pug', {
  name: 'Timothy'
}));
// "<p>Timothy's Pug source code!</p>"

1.2 和Express整合

Pug和Express結合，參考這個指南。

生產環境配置

Express中環境變量NODE_ENV用來標識當前應用是在開發環境還是生產環境。Express和Pug會根據這個環境變量自動修改一些配置選項，為用戶提供友好的“開箱即用”的使用體驗。

例如，在Express中使用Pug時，當process.env.NODE_ENV是“production”，compileDebug選項是false，默認情況下它是true。

可以通過設置app.locals或者res.locals為true或者false來覆蓋compileDebug和cache的默認選項值。還可以通過Express的app.disable/enable('view cache')放來開修改cache選項。

更多細節，參考Express的api文檔。

1.2.1 配置渲染引擎

1. 在app.js文件中設置渲染引擎：

// 設置渲染引擎
app.set('views', path.join(__dirname, './views'));
app.set('view engine', 'pug');

2. 在view目錄下創建pug文件

3. 在routers文件夾下的文件中創建路由以渲染pug文件，例如在routes\site.js文件中：

const express = require('express');
const router = express.Router();
/* GET users listing. */
router.get('/', function (req, res, next) {
  res.render('index', { title: '首頁', message: '首頁' })
});
module.exports = router;

1.3 API參考

本節詳細介紹Pug的api。

提示：可以直接在瀏覽器的console中訪問這些api，例如：pub.render('p Hello world!')。

選項

Pug中的方法參數如下：

filename：string

要編譯的文件的路徑和名字，使用相對路徑，保留后綴，默認是'.pug'。

basedir：string

所有文件的入口目錄。

doctype：string

如果沒有在Pug模板中指定doctype，可以在這里指定。

pretty：boolean | string

[不建議]在渲染HTML結果中添加一些空白字符串作為空格，以便閱讀。如果使用字符串，則將改字符串作為特定的空格使用（例如'\t'制表符）。不建議使用這個選項。由于這個選項修改空白的解析和渲染方式，通常會帶來意想不到的后果，因此后續版本中這個選項將被取消。默認值為false。

filters：object

自定義hash table過濾器，默認未定義。

self：boolean

使用默認自定義空間的locals，加快編譯速度，無需編寫變量，只須指定self.variable獲取locals。默認false。

debug：boolean

如果設置為true，tokens和函數體將輸出到日志中。

compileDebug：boolean

如果設置為true，錯誤信息中將包含方法源碼便于排查（測試環境會很有用）。該選項默認開啟，在正式環境關閉。

globals：Array<string>

在html模板中添加全局變量

cache：boolean

如果設置為true，將緩存編譯函數。使用pug源文件的名字作為cache的鍵值。render類的函數有這個選項，默認是false。

inlineRuntimeFunctions：boolean

內聯函數，代替require，在compileClient函數內，默認是true（不必包含運行時）。在其他編譯和渲染類型的函數中，這個選項默認是flase。

name：string

模板函數名。只在compileClient函數內。默認值是‘template’。

1.3.2 方法

pug.compile(source, ?options)

將一個Pug模板編譯成一個函數，根據不同參數可以被多次渲染。

source：string

要編譯的pug源文件。

options：?options

選項對象。

returns：function

返回值是一個根據本地配置生成html的函數。

var pug = require('pug');

// 生成編譯函數
var fn = pug.compile('string of pug', options);

// 調用編譯函數渲染html
var html = fn(locals);
// => '<string>of pug</string>'

pug.compileFile(path, ?options)

將一個pug源文件編譯成一個方法，根據不同參數可以多次調用。

path：string

pug文件的路徑

options：?options

選項對象

returns：function

返回值是一個根據本地配置生成html的函數。

var pug = require('pug');

// 生成編譯函數
var fn = pug.compileFile('path to pug file', options);

// 調用編譯函數渲染html
var html = fn(locals);
// => '<string>of pug</string>'

pug.compileClient(source, ?options)

將一個pug源文件編譯成一段JavaScript函數字符串，可以用在客戶端，調用這個函數返回html代碼。

path：string

pug文件的路徑

options：?options

選項對象

returns：function

返回值是一個JavaScript函數字符串

var pug = require('pug');

// 生成編譯函數
var fn = pug.compileClient('string of pug', options);

// 調用編譯函數生成一個函數字符串，這個函數函數返回html代碼
var html = fn(locals);
// => 'function template(locals) { return "<string>of pug</string>"; }'

pug.compileClientWithDependenciesTracked(source, ?options)

和compileClient方法類似，不同之處在與這個函數返回一個dom結構對象。如下：

{
  'body': 'function (locals) {...}',
  'dependencies': ['filename.pug']
}

僅當需要依賴來實現諸如監視Pug文件的更改之類的操作時，才應使用此方法。

pug.compileFileClient(path, ?options)

編譯一個Pug源文件便以為可在客戶端與pug運行時一起使用的JavaScript字符串。

path：string

pug文件的路徑

options：?options

選項對象

options.name：string

如果在options選項中指定了name屬性，它將作為客戶端模板函數的名稱

returns：function

返回值是一個JavaScript函數主體

假設下面是pug文件內容：

h1 This is a Pug template
h2 By #{author}

然后將pug文件編譯為函數字符串。

var fs = require('fs');
var pug = require('pug');

// 將模板編譯為函數字符串
var jsFunctionString = pug.compileFileClient('/path/to/pugFile.pug', {name: "fancyTemplateFun"});

// 可以將所有模板便以為template.js文件提供給客戶端
fs.writeFileSync("templates.js", jsFunctionString);

這是輸出函數字符串的樣子（寫到templates.js）

function fancyTemplateFun(locals) {
  var buf = [];
  var pug_mixins = {};
  var pug_interp;

  var locals_for_with = (locals || {});

  (function (author) {
    buf.push("<h1>This is a Pug template</h1><h2>By "
      + (pug.escape((pug_interp = author) == null ? '' : pug_interp))
      + "</h2>");
  }.call(this, "author" in locals_for_with ?
    locals_for_with.author : typeof author !== "undefined" ?
      author : undefined)
  );

  return buf.join("");
}

除了編譯的模板之外，還要確保將Pug運行時（node_modules / pug / runtime.js）發送給客戶端。如下：

<!DOCTYPE html>
<html>
  <head>
    <script src="/runtime.js"></script>
    <script src="/templates.js"></script>
  </head>

  <body>
    <h1>This is one fancy template.</h1>

    <script type="text/javascript">
      var html = window.fancyTemplateFun({author: "enlore"});
      var div = document.createElement("div");
      div.innerHTML = html;
      document.body.appendChild(div);
    </script>
  </body>
</html>

pug.render(source, ?options, ?callback)

source：string

要渲染的pug模板

options：?options

選項對象

callback: ?function

一個接受渲染結果回調函數，可以同步調用。

returns：function

返回值是一個JavaScript函數字符串

var pug = require('pug');

var html = pug.render('string of pug', options);
// => '<string>of pug</string>'

pug.renderFile(path, ?options, ?callback)

path：string

pug文件的路徑

options：?options

選項對象

callback: ?function

一個接受渲染結果回調函數，可以同步調用。

returns：function

返回值是HTML字符串

var pug = require('pug');

var html = pug.renderFile('path/to/file.pug', options);
// ...

1.4 filters選項

pug.filters

自定義的過濾器

該對象的語義與選項中的過濾器語義相同，但是全局應用于所有Pug編譯。當pug.filters和options.filters中都存在過濾器時，filters選項優先

提示：不推薦使用此屬性，而推薦使用濾鏡選項。

2. 語法參考

2.1 屬性

pug代碼中的標記屬性看起來和HTML（帶逗號），但是它的值只是普通的JavaScript。（注意：此頁面上的示例使用豎線字符（|）進行空白控制。）

a(href='google.com') Google
|
|
a(class='button' href='google.com') Google
|
|
a(class='button', href='google.com') Google

生成結果：

<a href="google.com">Google</a>
<a class="button" href="google.com">Google</a>
<a class="button" href="google.com">Google</a>

普通的JavaScript也可以正常工作

- var authenticated = true
body(class=authenticated ? 'authed' : 'anon')

<body class="authed"></body>

多個屬性

如果有多個屬性，還可以把他們放在多行

input(
  type='checkbox'
  name='agreement'
  checked
)

<input type="checkbox" name="agreement" checked="checked" />

如果你的JavaScript環境支持ES2015中的模板字符串（包含Node.js/io.js 1.0.0或后續版本），可以使用模板字符串，如果屬性值很長，這將會很有用。

input(data-json=`
  {
    "very-long": "piece of ",
    "data": true
  }
`)

<input data-json="
  {
    &quot;very-long&quot;: &quot;piece of &quot;,
    &quot;data&quot;: true
  }
" />

引用屬性

如果屬性名中包可能會干擾JavaScript語法的含奇怪字符，請使用雙引號或者單引號區分不同的屬性。包含[]和()（Angular2中經常使用）

//- In this case, `(click)` is treated as a
//- function call instead of a attribute name,
//- resulting in the unusual error.
div(class='div-class' (click)='play()')

報錯：

index.pug:4:11
    2| //- function call instead of a attribute name,
    3| //- resulting in the unusual error.
  > 4| div(class='div-class' (click)='play()')
-----------------^

Syntax Error: Assigning to rvalue

正確的寫法是：

div(class='div-class', (click)='play()')
div(class='div-class' '(click)'='play()')

<div class="div-class" (click)="play()"></div>
<div class="div-class" (click)="play()"></div>

屬性插值

注意：Pug/Jade的早期版本支持插值語法，例如：

a(href="/#{url}") Link

不再支持此語法。替代方法如下。（有關Pug v2與先前版本之間其他不兼容性的更多信息，請參閱我們的遷移指南。）

在屬性中包含變量，可以使用以下替代方法：

1.在JavaScript中使用屬性

- var url = 'pug-test.html';
a(href='/' + url) Link
|
|
- url = 'https://example.com/'
a(href=url) Another link

結果如下：

<a href="/pug-test.html">Link</a>
<a href="https://example.com/">Another link</a>

2.如果你的JavaScript環境支持ES2015（包含Node.js/io.js及更高版本），還可以使用其語法來簡化屬性

- var btnType = 'info'
- var btnSize = 'lg'
button(type='button' class='btn btn-' + btnType + ' btn-' + btnSize)
|
|
button(type='button' class=`btn btn-${btnType} btn-${btnSize}`)

結果如下

<button class="btn btn-info btn-lg" type="button"></button>
<button class="btn btn-info btn-lg" type="button"></button>

未轉義的屬性

默認情況下，所有屬性均被轉義（即特殊字符被替換成轉義序列）以防止攻擊（例如：跨站攻擊）。如果需要使用特殊符號，請使用 != 代替 =

div(escaped="<code>")
div(unescaped!="<code>")

結果如下：

<div escaped="&lt;code&gt;"></div>
<div unescaped="<code>"></div>

注意：未轉義的代碼是很危險的。必須確保清除用戶輸入中沒有這種代碼，以避免跨站腳本攻擊

布爾類型的屬性

pug中布爾類型的屬性被自動轉換為true，false。如果未指定任何值，則假定為true

input(type='checkbox' checked)
|
|
input(type='checkbox' checked=true)
|
|
input(type='checkbox' checked=false)
|
|
input(type='checkbox' checked=true.toString())

結果如下：

<input type="checkbox" checked="checked" />
<input type="checkbox" checked="checked" />
<input type="checkbox" />
<input type="checkbox" checked="true" />

ps：用兩個豎線分隔換行，pug代碼比html代碼還長！這是搞什么雞毛啊。

style屬性

像普通屬性一樣，style屬性可以是一個字符串；同時它也可以是一個對象，這樣生成樣式會很方便。

a(style={color: 'red', background: 'green'})

<a style="color:red;background:green;"></a>

class屬性

像普通屬性一樣，class屬性可以是一個字符串；同時它也可以是一個對象，這樣生成樣式會很方便。

- var classes = ['foo', 'bar', 'baz']
a(class=classes)
|
|
//- class屬性可以merge多個
a.bang(class=classes class=['bing'])

<a class="foo bar baz"></a>
<a class="bang foo bar baz bing"></a>

它也可以是將類名映射為true或false的對象。這對于應用條件類很有用

- var currentUrl = '/about'
a(class={active: currentUrl === '/'} href='/') Home
|
|
a(class={active: currentUrl === '/about'} href='/about') About

<a href="/">Home</a>
<a class="active" href="/about">About</a>

class選擇器語法

可以使用.classname語法創建class屬性

a.button

<a class="button"></a>

由于div是一個常用的dom，如果聲樂標簽名，默認生成一個dom，如下：

.content

<div class="content"></div>

ps：這個比較人性化

ID語法

使用id語法#idname可以創建元素

a#main-link

<a id="main-link"></a>

由于div是一個常用的dom，如果聲樂標簽名，默認生成一個dom，如下：

#content

<div id="content"></div>

自定義屬性

使用&attributes語法可以創建多個自定義屬性

div#foo(data-bar="foo")&attributes({'data-foo': 'bar'})

<div id="foo" data-bar="foo" data-foo="bar"></div>

上面例子中啟示可以使用object語法創建多個屬性，也可以使用變量靈活處理。（參考：Mixin屬性）

- var attributes = {};
- attributes.class = 'baz';
div#foo(data-bar="foo")&attributes(attributes)

<div class="baz" id="foo" data-bar="foo"></div>

注意：使用&attributes屬性不會自動轉義，使用的時候必須注意驗證用戶輸入，避免跨站攻擊。使用mixin調用可以自動完成轉義。

2.2 Case語法

在JavaScript中case語法是和switch配合使用，pug中也可以使用switch...case，如下：

- var friends = 10
case friends
  when 0
    p you have no friends
  when 1
    p you have a friend
  default
    p you have #{friends} friends

<p>you have 10 friends</p>

Case

pug中的case語法和JavaScript中的switch類似，如下：

- var friends = 0
case friends
  when 0
  when 1
    p you have very few friends
  default
    p you have #{friends} friends

<p>you have very few friends</p>

但是和JavaScript中的case還是有區別，pud中沒有不是switch-case，而是case-when，如果不想在switch語句中輸出任何內容，可以添加一個顯式的break，如下：

- var friends = 0
case friends
  when 0
    - break
  when 1
    p you have very few friends
  default
    p you have #{friends} friends

這個case語句不會輸出任何內容

塊

case塊語法也可以像下面這樣：

- var friends = 1
case friends
  when 0: p you have no friends
  when 1: p you have a friend
  default: p you have #{friends} friends

<p>you have a friend</p>

2.3 內聯代碼

Pug允許在模版中編寫內聯JavaScript代碼。有三種類型的代碼：Unbuffered（未緩存？），Buffered（緩沖？）和Unescaped Buffered（未轉義的緩沖）

Unbuffered Code

Unbuffered代碼以-開頭，注意這一句不會輸出任何內容

- for (var x = 0; x < 3; x++)
  li item

<li>item</li>
<li>item</li>
<li>item</li>

當然，也支持塊輸出：

-
  var list = ["Uno", "Dos", "Tres",
          "Cuatro", "Cinco", "Seis"]
each item in list
  li= item

<li>Uno</li>
<li>Dos</li>
<li>Tres</li>
<li>Cuatro</li>
<li>Cinco</li>
<li>Seis</li>

Buffered Code

Buffered代碼以=開頭。它先計算JavaScript表達式并輸出結果，為安全起見，Buffered代碼首先轉義為HTML

p
  = 'This code is <escaped>!'

<p>This code is &lt;escaped&gt;!</p>

它也可以以內聯屬性編寫，并支持所有JavaScript表達式

p= 'This code is' + ' <escaped>!'

<p>This code is &lt;escaped&gt;!</p>

Unescaped Buffered Code

未轉義的Buffered代碼以!=開頭。它計算JavaScript表達式并輸出結果，但是輸出的Html代碼是未轉義的，因此對用戶而言是不安全的

p
  != 'This code is <strong>not</strong> escaped!'

<p>This code is <strong>not</strong> escaped!</p>

和轉義的Buffered代碼一樣，它可以以內聯形式編寫屬性，支持所有的JavaScript表達式

p!= 'This code is' + ' <strong>not</strong> escaped!'

<p>This code is <strong>not</strong> escaped!</p>

注意：未轉義的Buffered代碼可能是非常危險的。必須處理用戶輸入，避免跨站攻擊

2.5 注釋

緩沖注釋和JavaScript中的單行注釋一樣，它的行為類似于標記標簽，渲染的時候生成html注釋。

// just some paragraphs
p foo
p bar

<!-- just some paragraphs-->
<p>foo</p>
<p>bar</p>

Pug還支持無緩沖注釋，只需在注釋開頭加上字符-。這種注釋只是對Pug代碼本身進行注釋，不會呈現在HTML中。

//- will not output within markup
p foo
p bar

<p>foo</p>
<p>bar</p>

塊注釋

塊注釋方式如下：

body
  //-
    Comments for your template writers.
    Use as much text as you want.
  //
    Comments for your HTML readers.
    Use as much text as you want.

<body>
  <!--Comments for your HTML readers.
Use as much text as you want.-->
</body>

條件注釋

Pug中的條件注釋和html一樣，沒有特殊的語法。（條件注釋是為舊版本的Internet Explorer添加回退標記的一種特殊方法。）

Pug中以<開頭被視為純文本，普通的JavaScript條件注釋在Pug中可以正常工作。

doctype html

<!--[if IE 8]>
<html lang="en" class="lt-ie9">
<![endif]-->
<!--[if gt IE 8]><!-->
<html lang="en">
<!--<![endif]-->
body
  p Supporting old web browsers is a pain.

</html>

<!DOCTYPE html>
<!--[if IE 8]>
<html lang="en" class="lt-ie9">
<![endif]-->
<!--[if gt IE 8]><!-->
<html lang="en">
<!--<![endif]-->
<body>
  <p>Supporting old web browsers is a pain.</p>
</body>

</html>

2.6 條件語句

Pug中條件語句可以不使用括號包裹

- var user = { description: 'foo bar baz' }
- var authorised = false
#user
  if user.description
    h2.green Description
    p.description= user.description
  else if authorised
    h2.blue Description
    p.description.
      User has no description,
      why not add one...
  else
    h2.red Description
    p.description User has no description

<div id="user">
  <h2 class="green">Description</h2>
  <p class="description">foo bar baz</p>
</div>

Pug還提供條件判斷語句unless，它和if是相反的，如下兩種判斷是等價的。

unless user.isAnonymous
  p You're logged in as #{user.name}

if !user.isAnonymous
  p You're logged in as #{user.name}

2.7 文檔類型

doctype html

<!DOCTYPE html>

文檔類型縮寫

常用文檔內省有一些快捷方式：

doctype html

<!DOCTYPE html>

doctype xml

<?xml version="1.0" encoding="utf-8" ?>

doctype transitional

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

doctype strict

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

doctype frameset

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd">

doctype 1.1

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">

doctype basic

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN" "http://www.w3.org/TR/xhtml-basic/xhtml-basic11.dtd">

doctype mobile

<!DOCTYPE html PUBLIC "-//WAPFORUM//DTD XHTML Mobile 1.2//EN" "http://www.openmobilealliance.org/tech/DTD/xhtml-mobile12.dtd">

doctype plist

<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">

自定義文檔類型

還可以自定義自己的文檔類型，如下：

doctype html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN"

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN">

Doctype選項

除了在輸出中緩沖外，Pug中的doctype還可能影響編譯。例如，自動關閉的標簽是否以/>或>結尾取決于是否指定了HTML或XML。布爾屬性的輸出也可能會受到影響。

如果由于其他原因無法使用doctype關鍵字（例如，僅渲染HTML片段），但是仍然希望指定模板的doctype，則可以通過doctype選項進行操作。

var pug = require('pug');

var source = 'img(src="foo.png")';

pug.render(source);
// => '<img src="foo.png"/>'

pug.render(source, {doctype: 'xml'});
// => '<img src="foo.png"></img>'

pug.render(source, {doctype: 'html'});
// => '<img src="foo.png">'

2.7 過濾器

過濾器允許在Pug模板中使用其他的語言，他們作為一塊文本輸入。要將選項傳遞給過濾器，需要在過濾器后的括號內添加（就像標記屬性一樣）例如：

:less(ieCompat=false)

所有JSTransformer模塊都可以用作Pug過濾器。流行的過濾器包括：babel，：uglify-js，：scss和：markdown-it。請查看JSTransformer的文檔，以了解特定過濾器支持的選項。

如果找不到適合您的用例的過濾器，則可以編寫自己的自定義過濾器。

例如，如果您希望能夠在Pug模板中使用CoffeeScript和Markdown（使用Markdown-it渲染器），則首先要確保已安裝以下插件：

$ npm install --save jstransformer-coffee-script
$ npm install --save jstransformer-markdown-it

現在，您應該能夠使用以下模板渲染：

:markdown-it(linkify langPrefix='highlight-')
  # Markdown

  Markdown document with http://links.com and

  ```js
  var codeBlocks;
  ```
script
  :coffee-script
    console.log 'This is coffee script'

<h1>Markdown</h1>
<p>Markdown document with <a href="http://links.com">http://links.com</a> and</p>
<pre><code class="highlight-js">var codeBlocks;
</code></pre>
<script>
  (function() {
    console.log('This is coffee script');

  }).call(this);
</script>

警告：過濾器在編譯時渲染。這使它們快速運行，但也意味著它們不能支持動態內容或選項。默認情況下，瀏覽器中的編譯無法訪問基于JSTransformer的篩選器，除非JSTransformer模塊已明確通過CommonJS平臺打包（例如Browserify或Webpack）。實際上，您正當前這個頁面正式使用使用Browserify打包使得過濾器在瀏覽器中可用。在服務器上預編譯的模板沒有此限制。

內聯語法

如果過濾器的內容比較短，甚至可以像使用標簽那樣使用過濾器。

p
  :markdown-it(inline) **BOLD TEXT**

p.
  In the midst of a large amount of plain
  text, suddenly a wild #[:markdown-it(inline) *Markdown*]
  appeared.

<p><strong>BOLD TEXT</strong></p>
<p>In the midst of a large amount of plain text, suddenly a wild <em>Markdown</em> appeared.
</p>

包含語法

在使用過濾器的時候，可以通過包含語法將外部文件包含進來。

嵌套的過濾器

可以在同一文本快上應用多個過濾器，為此只需在同一行使用過濾器語法。

過濾器以相反的順序應用。文本首先傳遞到最后一個過濾器；然后，結果將傳遞到倒數第二個過濾器，依此類推。在以下示例中，腳本首先由babel轉換，然后由cdata-js轉換。

script
  :cdata-js:babel(presets=['es2015'])
    const myFunc = () => `This is ES2015 in a CD${'ATA'}`;

f.default.existsSync is not a function

自定義過濾器

通過filters選項，可以定義自定義過濾器

options.filters = {
  'my-own-filter': function (text, options) {
    if (options.addStart) text = 'Start\n' + text;
    if (options.addEnd)   text = text + '\nEnd';
    return text;
  }
};

p
  :my-own-filter(addStart addEnd)
    Filter
    Body

<p>
  Start
  Filter
  Body
  End
</p>

2.8 文件包含

包含語法允許在一個Pug文件中包含另一個Pug文件。

//- index.pug
doctype html
html
  include includes/head.pug
  body
    h1 My Site
    p Welcome to my super lame site.
    include includes/foot.pug

//- includes/head.pug
head
  title My Site
  script(src='/javascripts/jquery.js')
  script(src='/javascripts/app.js')

//- includes/foot.pug
footer#footer
  p Copyright (c) foobar

結果如下：

<!DOCTYPE html>
<html>
<head>
  <title>My Site</title>
  <script src="/javascripts/jquery.js"></script>
  <script src="/javascripts/app.js"></script>
</head>
<body>
  <h1>My Site</h1>
  <p>Welcome to my super lame site.</p>
  <footer id="footer">
    <p>Copyright (c) foobar</p>
  </footer>
</body>
</html>

如果使用絕對路徑，可以使用options.basedir變量拼接，否則按照相對當前文件的路徑解析。

如果沒有后綴，.pug將作為默認后綴。

包含純文本

包含的文件不是pug，則當做純文本來處理。

//- index.pug
doctype html
html
  head
    style
      include style.css
  body
    h1 My Site
    p Welcome to my super lame site.
    script
      include script.js

/* style.css */
h1 {
  color: red;
}

// script.js
console.log('You are awesome');

<!DOCTYPE html>
<html>

<head>
  <style>
    /* style.css */

    h1 {
      color: red;
    }
  </style>
</head>

<body>
  <h1>My Site</h1>
  <p>Welcome to my super lame site.</p>
  <script>
    // script.js
    console.log('You are awesome');
  </script>
</body>
</html>

包含過濾器

可以將過濾器與當前Pug文件結合使用。

//- index.pug
doctype html
html
  head
    title An Article
  body
    include:markdown-it article.md

# article.md

This is an article written in markdown.

<!DOCTYPE html>
<html>
  <head>
    <title>An Article</title>
  </head>
  <body>
    <h1>article.md</h1>
    <p>This is an article written in markdown.</p>
  </body>
</html>

2.8 模板繼承

Pug支持模板繼承，模板繼承通過關鍵字“block”和“extends”實現。在模板中，block關鍵字表示這個塊在子模塊中可以被替換。此過程是遞歸的。下面示例定義了頭部，塊內容和腳。

//- layout.pug
html
  head
    title My Site - #{title}
    block scripts
      script(src='/jquery.js')
  body
    block content
    block foot
      #footer
        p some footer content

創建新Pug文件來繼承上面的Pug模板，在新的文件中使用extends關鍵字來繼承，然后Pug模板中的block塊會被繼承下來。

注意foot塊沒有定義，所以使用父模板中的fug塊，輸出“some footer content”。而其他塊將在自身基礎上繼承父模板的內容。

//- page-a.pug
extends layout.pug

block scripts
  script(src='/jquery.js')
  script(src='/pets.js')

block content
  h1= title
  - var pets = ['cat', 'dog']
  each petName in pets
    include pet.pug

//- pet.pug
p= petName

還可以覆蓋某個塊以提供其他的塊，在下面例子中，content塊中暴露了sidebar和primary塊（但是子模塊可以完全覆蓋掉content）

//- sub-layout.pug
extends layout.pug

block content
  .sidebar
    block sidebar
      p nothing
  .primary
    block primary
      p nothing

//- page-b.pug
extends sub-layout.pug

block content
  .sidebar
    block sidebar
      p nothing
  .primary
    block primary
      p nothing

塊的前置，后置

Pug允許替換（默認），前置，后置一個塊。

假設您希望在每個頁面的head塊中都包含默認腳本。您可以這樣做：

//- layout.pug
html
  head
    block head
      script(src='/vendor/jquery.js')
      script(src='/vendor/caustic.js')
  body
    block content

例如，現在考慮您的JavaScript游戲頁面。您需要一些與游戲相關的腳本以及這些默認腳本。您可以簡單地添加塊：

//- page.pug
extends layout.pug

block append head
  script(src='/vendor/three.js')
  script(src='/game.js')

在使用append，prepend的時候可以省去block關鍵字，如下：

//- page.pug
extends layout

append head
  script(src='/vendor/three.js')
  script(src='/game.js')

常見錯誤

Pug的模板繼承是一項強大的功能，可讓您將復雜的頁面模板結構拆分為更小，更簡單的文件。但是，如果將許多模板鏈接在一起，則可能會使頁面復雜得不可維護。

請注意，只有命名塊(block)和混合定義可以出現在子模板的頂層（未縮進），頂層不能出現其他內容，如lin()，script，和普通的標簽如div(class="content")。這個很重要！否則會報錯：Only named blocks and mixins can appear at the top level of an extending template。父模板定義頁面的整體結構，子模板只能附加，添加或替換特定的標記和邏輯塊。如果子模板試圖在塊外添加內容，Pug將無法知道將其放置在最終頁面的何處。

使用未緩沖的代碼，如果需要在子模塊中使用變量，則可以使用下面幾種不同的方法：

將變量添加到Pug選項對象，或在父模板的未緩沖代碼中定義它們。子模板將繼承這些變量。
在子模板的塊中定義變量。擴展模板必須至少包含一個塊，否則將為空-只需在此處定義變量即可。

出于同樣的原因，Pug的緩沖注釋不能出現在擴展模板的頂層：它們產生的HTML注釋在生成的HTML中無處渲染。（但是，無緩沖的Pug注釋仍然可以）

2.10 插值

Pug提供多種方式在html中插入一個值。

轉義的字符串

下面例子中title，author，theGreat變量作為本地變量被插入到代碼中。

- var title = "On Dogs: Man's Best Friend";
- var author = "enlore";
- var theGreat = "<span>escape!</span>";

h1= title
p Written with love by #{author}
p This will be safe: #{theGreat}

<h1>On Dogs: Man's Best Friend</h1>
<p>Written with love by enlore</p>
<p>This will be safe: &lt;span&gt;escape!&lt;/span&gt;</p>

title演示的是最基本的使用方法，再是在#{}中使用變量將會被轉義，并將結果緩沖到要渲染的模板中。

還可以使用表達式，只要是合法的，任何地方都可以使用。

- var msg = "not my inside voice";
p This is #{msg.toUpperCase()}

<p>This is NOT MY INSIDE VOICE</p>

Pug可以自動找出判斷表達式是否結束，甚至可以包含未轉義的符號，例如}

p No escaping for #{'}'}!

<p>No escaping for }!</p>

如果想在html中輸出#{，可以將其轉義，或者使用插值。

p Escaping works with \#{interpolation}
p Interpolation works with #{'#{interpolation}'} too!

<p>Escaping works with #{interpolation}</p>
<p>Interpolation works with #{interpolation} too!</p>

未轉義的字符串

可以將未轉義的字符串緩沖在模板中。

- var riskyBusiness = "<em>Some of the girls are wearing my mother's clothing.</em>";
.quote
  p Joel: !{riskyBusiness}

<div class="quote">
  <p>Joel: <em>Some of the girls are wearing my mother's clothing.</em></p>
</div>

注意：如果原內容來自用戶輸入，則將未轉義的內容緩沖到模板中可能帶來很大的風險。永遠不要相信用戶的輸入。

標簽插入

不僅可以使用JavaScript插入變量，還可以在Pug內容中插入標簽，如下：

p.
  This is a very long and boring paragraph that spans multiple lines.
  Suddenly there is a #[strong strongly worded phrase] that cannot be
  #[em ignored].
p.
  And here's an example of an interpolated tag with an attribute:
  #[q(lang="es") ?Hola Mundo!]

<p>This is a very long and boring paragraph that spans multiple lines. Suddenly there is a <strong>strongly worded phrase</strong> that cannot be
  <em>ignored</em>.</p>
<p>And here's an example of an interpolated tag with an attribute:
  <q lang="es">?Hola Mundo!</q></p>

您可以通過編寫與Pug內聯的HTML標簽來完成相同的事，但是，編寫Pug的目的是什么？將內嵌的Pug標簽聲明包裝在＃[]中，它將被評估并緩沖到其包含標簽的內容中。

空格控制

默認情況下，Pug會刪除標記之前和之后所有的空格，如下：

p
  | If I don't write the paragraph with tag interpolation, tags like
  strong strong
  | and
  em em
  | might produce unexpected results.
p.
  If I do, whitespace is #[strong respected] and #[em everybody] is happy.

<p>If I don't write the paragraph with tag interpolation, tags like<strong>strong</strong>and<em>em</em>might produce unexpected results.</p>
<p>If I do, whitespace is <strong>respected</strong> and <em>everybody</em> is happy.</p>

有關此主題的更多討論，請參見Plain Text。

2.11 循環輸出

Pug中支持兩種方式的循環輸出：each和while

each

Pug中第一種循環輸出語法each可以迭代模板中的數組和對象。

ul
  each val in [1, 2, 3, 4, 5]
    li= val

<ul>
  <li>1</li>
  <li>2</li>
  <li>3</li>
  <li>4</li>
  <li>5</li>
</ul>

循環中可以從第二個參數中獲取當前index

ul
  each val, index in ['zero', 'one', 'two']
    li= index + ': ' + val

<ul>
  <li>0: zero</li>
  <li>1: one</li>
  <li>2: two</li>
</ul>

Pug中甚至可以迭代中獲取對象的key

ul
  each val, index in {1:'one',2:'two',3:'three'}
    li= index + ': ' + val

<ul>
  <li>1: one</li>
  <li>2: two</li>
  <li>3: three</li>
</ul>

要迭代的對象或數組只是純JavaScript。因此，它可以是變量，也可以是函數調用的結果，或者幾乎是其他任何東西。

- var values = [];
ul
  each val in values.length ? values : ['There are no values']
    li= val

<ul>
  <li>There are no values</li>
</ul>

如果數組或對象不包含要迭代的值，則還可以添加一個else塊，該塊將被執行。以下等效于上面的示例：

- var values = [];
ul
  each val in values
    li= val
  else
    li There are no values

<ul>
  <li>There are no values</li>
</ul>

還可以使用for關鍵字代替each，效果是一樣的。

while

還可以使用while來迭代，如下：

- var n = 0;
ul
  while n < 4
    li= n++

<ul>
  <li>0</li>
  <li>1</li>
  <li>2</li>
  <li>3</li>
</ul>

2.12 Mixins

Mixins允許創建可重用的塊。

//- Declaration
mixin list
  ul
    li foo
    li bar
    li baz
//- Use
+list
+list

<ul>
  <li>foo</li>
  <li>bar</li>
  <li>baz</li>
</ul>
<ul>
  <li>foo</li>
  <li>bar</li>
  <li>baz</li>
</ul>

Mixins允許傳入參數

mixin pet(name)
  li.pet= name
ul
  +pet('cat')
  +pet('dog')
  +pet('pig')

<ul>
  <li class="pet">cat</li>
  <li class="pet">dog</li>
  <li class="pet">pig</li>
</ul>

混入塊

Mixins還可以使用Pug塊作為內容：

mixin article(title)
  .article
    .article-wrapper
      h1= title
      if block
        block
      else
        p No content provided

+article('Hello world')

+article('Hello world')
  p This is my
  p Amazing article

<div class="article">
  <div class="article-wrapper">
    <h1>Hello world</h1>
    <p>No content provided</p>
  </div>
</div>
<div class="article">
  <div class="article-wrapper">
    <h1>Hello world</h1>
    <p>This is my</p>
    <p>Amazing article</p>
  </div>
</div>

混合屬性

混合還可以傳入一個隱式參數，可以用來給屬性賦值

mixin link(href, name)
  //- attributes == {class: "btn"}
  a(class!=attributes.class href=href)= name

+link('/foo', 'foo')(class="btn")

<a class="btn" href="/foo">foo</a>

注意：默認情況下，屬性中的值已被轉義！您應該使用！=以避免再次轉義它們。（另請參見未轉義的屬性。）

可以在混合中使用&attributes：

mixin link(href, name)
  a(href=href)&attributes(attributes)= name

+link('/foo', 'foo')(class="btn")

<a class="btn" href="/foo">foo</a>

注意：語法+ link（class =“ btn”）也是有效的，并且等價于+ link（）（class =“ btn”），因為Pug會嘗試檢測括號的內容是屬性還是參數。但是，建議您使用第二種語法，因為您沒有明確傳遞任何參數，并且確保第一個括號是參數列表。

默認參數值

還可以設置參數的默認值，和ES6中設置函數的默認參數值是類似的：

//- Declaration
mixin article(title='Default Title')
  .article
    .article-wrapper
      h1= title

//- Use
+article()

+article('Hello world')

<div class="article">
  <div class="article-wrapper">
    <h1>Default Title</h1>
  </div>
</div>
<div class="article">
  <div class="article-wrapper">
    <h1>Hello world</h1>
  </div>
</div>

解析參數

在Mixins中可以使用解析參數來傳遞多個參數

mixin list(id, ...items)
  ul(id=id)
    each item in items
      li= item

+list('my-list', 1, 2, 3, 4)

<ul id="my-list">
  <li>1</li>
  <li>2</li>
  <li>3</li>
  <li>4</li>
</ul>

2.13 純文本

Pug提供了四種獲取純文本的方法-即將未經處理的代碼，文本渲染在HTML中，有時候會很有用。

純文本仍然使用標記和字符串插值，但該行的第一個單詞不是Pug標記。并且由于不會轉義純文本，因此您還可以包括文字HTML。

一個常見的缺陷是在渲染的HTML中使用空白，將在后面討論。

內聯標簽

插入純文本最早的方式是使用內斂標簽。第一個詞是標簽名，后面所有內容都是標簽的內容。如果內容很短或者不介意這一行內容太長，這樣是沒有任何問題的。

p This is plain old <em>text</em> content.

<p>This is plain old <em>text</em> content.</p>

HTML文本

當整行以左尖括號（<）開頭時，它們也被視為純文本，有時不方便的地方編寫文字HTML標簽很有用。例如，一種用例是條件注釋。由于文字HTML標記不會得到處理，因此與Pug標記不同，它們不會自動關閉。

<html>
body
  p Indenting the body tag here would make no difference.
  p HTML itself isn't whitespace-sensitive.
</html>

<html>
<body>
  <p>Indenting the body tag here would make no difference.</p>
  <p>HTML itself isn't whitespace-sensitive.</p>
</body>
</html>

豎線隔開

將純文本添加到模板的另一種方法是在行的前面加上豎線字符（|）。如我們稍后在“空白內容”部分中所述，此方法對于將純文本與內聯標簽混合很有用。

p
  | The pipe always goes at the beginning of its own line,
  | not counting indentation.

<p>The pipe always goes at the beginning of its own line, not counting indentation.</p>

通常，您可能希望標簽中包含大塊文本。一個很好的例子是在script和style標簽中編寫JavaScript和CSS代碼。為此，只需添加一個逗號，如果標簽具有屬性，則在標簽名稱之后，或者在右括號之后。

注意在tag和逗號之間不能有空格，標簽的純文本內容必須縮進一級。

script.
  if (usingPug)
    console.log('you are awesome')
  else
    console.log('use pug')

<script>
  if (usingPug)
    console.log('you are awesome')
  else
    console.log('use pug')
</script>

還可以在tag標簽內部再使用逗號創建一個塊：

div
  p This text belongs to the paragraph tag.
  br
  .
    This text belongs to the div tag.

<div>
  <p>This text belongs to the paragraph tag.</p><br/>This text belongs to the div tag.</div>

空格控制

處理HTML中的空白可能是學習Pug最麻煩的地方，不過掌握竅門之后就很容易了。只需要記住兩點：

Pug默認刪除縮進，和元素間的所有空白。因此html結束符將和下一個html開始符相鄰。這對一些塊級元素（例如段落）是沒有問題的，因為他們在瀏覽器中是單獨的段落（處理使用css的display屬性修）。但是如果確實需要在元素之間插入空格，參考下面第二條：
Pug保留元素內的空白，包括：
文本中的所有空格
超出塊縮進的空白區域
尾部空格
純文本塊內或者連續豎線換行之間的

所以，Pug刪除了標簽之間的空格，保留標簽內部的空格。這樣可以控制是否可以在tag或者純文本中出的空格。甚至單詞之間的空格。

| You put the em
em pha
| sis on the wrong syl
em la
| ble.

You put the em<em>pha</em>sis on the wrong syl<em>la</em>ble.

去掉空格需要考慮控制標簽和文本是否連接在一起。

a ...sentence ending with a link
| .

<a>...sentence ending with a link</a>.

如果需要添加空格，參考下面方法

不推薦的做法

根據需要的空格，可以在文本的開頭（在塊縮進，豎線字符和/或標記之后）添加一個額外的空格。或者，您可以在文本末尾添加尾隨空格。

| Hey, check out 
a(href="http://example.biz/kitteh.png") this picture
|  of my cat!

| Hey, check out 
a() this picture
|  of my cat!

上面的解決方案可以很好地工作，但是肯定會有些危險：默認情況下，許多代碼編輯器都會在保存時刪除尾隨空格。你的同時可能必須配置編輯器，以防止自動刪除部空格。

參考連接：https://pugjs.org/api/getting-started.html

posted @ 2019-11-21 18:04 nd 閱讀(4774) 評論(0) 收藏舉報

刷新頁面返回頂部

pug參考文檔

1. API

1.1 開始

1.2 和Express整合

1.2.1 配置渲染引擎

1.3 API參考

選項

1.3.2 方法

pug.compile(source, ?options)

pug.compileFile(path, ?options)

pug.compileClient(source, ?options)

pug.compileClientWithDependenciesTracked(source, ?options)

pug.compileFileClient(path, ?options)

pug.render(source, ?options, ?callback)

pug.renderFile(path, ?options, ?callback)

1.4 filters選項

pug.filters

2. 語法參考

2.1 屬性

多個屬性

引用屬性

屬性插值

未轉義的屬性

布爾類型的屬性

style屬性

class屬性

class選擇器語法

ID語法

自定義屬性

2.2 Case語法

Case

塊

2.3 內聯代碼

Unbuffered Code

Buffered Code

Unescaped Buffered Code

2.5 注釋

塊注釋

條件注釋

2.6 條件語句

2.7 文檔類型

文檔類型縮寫

自定義文檔類型

Doctype選項

2.7 過濾器

內聯語法

包含語法

嵌套的過濾器

自定義過濾器

2.8 文件包含

包含純文本

包含過濾器

2.8 模板繼承

塊的前置，后置

常見錯誤

2.10 插值

轉義的字符串

未轉義的字符串

標簽插入

空格控制

2.11 循環輸出

each

while

2.12 Mixins

混入塊

混合屬性

默認參數值

解析參數

2.13 純文本

內聯標簽

HTML文本

豎線隔開

推薦的方法

不推薦的做法

公告