Categories
BLOG

pug pipe

Plain Text

Pug provides four ways of getting plain text — that is, any code or text content that should go, mostly unprocessed, directly into the rendered HTML. They are useful in different situations.

Plain text does still use tag and string interpolation, but the first word on the line is not a Pug tag. And because plain text is not escaped, you can also include literal HTML.

One common pitfall here is managing whitespace in the rendered HTML. We’ll talk about that at the end of this page.

Inline in a Tag В¶

The easiest way to add plain text is inline. The first term on the line is the tag itself. Everything after the tag and one space will be the text contents of that tag. This is most useful when the plain text content is short (or if you don’t mind lines running long).

Literal HTML В¶

Whole lines are also treated as plain text when they begin with a left angle bracket ( ), which may occasionally be useful for writing literal HTML tags in places that could otherwise be inconvenient. For example, one use case is conditional comments. Since literal HTML tags do not get processed, they do not self-close, unlike Pug tags.

Piped Text В¶

Another way to add plain text to templates is to prefix a line with a pipe character ( | ). This method is useful for mixing plain text with inline tags, as we discuss later, in the Whitespace Control section.

Block in a Tag В¶

Often you might want large blocks of text within a tag. A good example is writing JavaScript and CSS code in the script and style tags. To do this, just add a . right after the tag name, or after the closing parenthesis, if the tag has attributes.

There should be no space between the tag and the dot. Plain text contents of the tag must be indented one level:

You can also create a dot block of plain text after other tags within the parent tag.

Whitespace Control В¶

Managing the whitespace of the rendered HTML is one of the trickiest parts about learning Pug. Don’t worry, though, you’ll get the hang of it soon enough.

You just need to remember two main points about how whitespace works. When compiling to HTML:

  1. Pug removes indentation, and all whitespace between elements.
    • So, the closing tag of an HTML element will touch the opening tag of the next. This is generally not a problem for block-level elements like paragraphs, because they will still render as separate paragraphs in the web browser (unless you have changed their CSS display property). See the methods described below, however, for when you do need to insert space between elements.
  2. Pug preserves whitespace within elements, including:
    • all whitespace in the middle of a line of text.
    • leading whitespace beyond the block indentation.
    • trailing whitespace.
    • line breaks within a plain text block, or between consecutive piped lines.

So…Pug drops the whitespace between tags, but keeps the whitespace inside them. The value here is that it gives you full control over whether tags and/or plain text should touch. It even lets you place tags in the middle of words.

The trade-off is that it requires you to think about and take control over whether tags and text touch.

If you need the text and/or tags to touch — perhaps you need a period to appear outside the hyperlink at the end of a sentence — this is easy, as it’s basically what happens unless you tell Pug otherwise.

If you need to add space, you have a few options:

Recommended Solutions В¶

You could add one or more empty piped lines — a pipe with either spaces or nothing after it. This will insert whitespace in the rendered HTML.

If your inline tags don’t require many attributes, you may find it easiest to use tag interpolation, or literal HTML, within a plain text block.

Not recommended В¶

Depending on where you need the whitespace, you could add an extra space at the beginning of the text (after the block indentation, pipe character, and/or tag). Or you could add a trailing space at the end of the text.

NOTE the trailing and leading spaces here:

The above solution works perfectly well, but is admittedly perhaps a little dangerous: many code editors by default will remove trailing whitespace on save. You and all your contributors may have to configure your editors to prevent automatic trailing whitespace removal.

Plain Text Pug provides four ways of getting plain text — that is, any code or text content that should go, mostly unprocessed, directly into the rendered HTML. They are useful in different

Attributes

Tag attributes look similar to HTML (with optional commas), but their values are just regular JavaScript.

(NOTE: Examples on this page use the pipe character ( | ) for whitespace control.)

Normal JavaScript expressions work fine, too:

Multiline Attributes В¶

If you have many attributes, you can also spread them across many lines:

If your JavaScript runtime supports ES2015 template strings (including Node.js/io.js 1.0.0 and later), you can use that syntax for attributes. This is really useful for attributes with really long values:

Quoted Attributes В¶

If your attribute name contains odd characters that might interfere with JavaScript syntax, either quote it using “” or ” , or use commas to separate different attributes. Examples of such characters include [] and () (frequently used in Angular 2).

Attribute Interpolation В¶

Caution

Previous versions of Pug/Jade supported an interpolation syntax such as:

This syntax is no longer supported. Alternatives are found below. (Check our migration guide for more information on other incompatibilities between Pug v2 and previous versions.)

Here are some alternatives you can use to include variables in your attribute:

Simply write the attribute in JavaScript:

If your JavaScript runtime supports ES2015 template strings (including Node.js/io.js 1.0.0 and later), you can also use its syntax to simplify your attributes:

Unescaped Attributes В¶

By default, all attributes are escaped—that is,special characters are replaced with escape sequences—to prevent attacks (such as cross site scripting). If you need to use special characters, use != instead of = .

Caution

Unescaped buffered code can be dangerous. You must be sure to sanitize any user inputs to avoid cross-site scripting.

Boolean Attributes В¶

Boolean attributes are mirrored by Pug. Boolean values ( true and false ) are accepted. When no value is specified true is assumed.

If the doctype is html , Pug knows not to mirror the attribute, and instead uses the terse style (understood by all browsers).

Style Attributes В¶

The style attribute can be a string, like any normal attribute; but it can also be an object, which is handy when styles are generated by JavaScript.

Class Attributes В¶

The class attribute can be a string, like any normal attribute; but it can also be an array of class names, which is handy when generated from JavaScript.

It can also be an object which maps class names to true or false values. This is useful for applying conditional classes

Attributes Tag attributes look similar to HTML (with optional commas), but their values are just regular JavaScript. (NOTE: Examples on this page use the pipe character ( | ) for whitespace