Breaking Changes

[ForbesLindesay]

This issue lists known breaking changes from jade to pug@2.0.0. If you think you've found another breaking change, please open a separate issue so it can be triaged. I'm going to lock this issue to collaborators only.

General Changes

• include and extend both default to adding a .pug extension if there is no extension, rather than a .jade extension. You should ideally rename all .jade files to .pug files, failing that you will need to explicitly add a .jade extension to include and extend statements.

  Removed/Changed syntax

Old	New	Explanation
mixin foo('whatever')	+foo('whatever')	We removed the legacy syntax for calling a mixin to make it easier to differentiate between declaration and calls
a(href="#{link}") a(href='before#{link}after')	a(href=link) a(href=`before${link}after`) (on Node.js/io.js ≥ 1.0.0) a(href='before' + link + 'after') (everywhere)	We removed support for interpolation in attributes since it was unnecessarily complex in implementation and tended to delay users learning that they can just use any JavaScript value in place of attributes
- each a in b	each a in b	each is not part of the JavaScript syntax, so the use of each "keyword" in a JavaScript line is confusing as well as hackish (in terms of implementation). Simply remove -  and your code should work again.

Changed Output

Input	Old	New	Explanation
input(value=new Date())	<input value="Wed Apr 13 2016 14:36:25 GMT+0100 (BST)"/>	<input value="2016-04-13T13:36:25.000Z"/>	We now always use the ISO representation of dates
input(value={some: 'object'})	<input value="[object Object]"/>	<input value='{"some":"object"}'/>	We used to only JSON.stringify if the attribute started with data-. We've made this more consistent.

Removed APIs

Most of the removed APIs never should have been public in the first place: they make it possible to pollute modules visible in the global scope.

Exported	Explanation
selfClosing	Custom self-closing tags WILL be allowed as a plugin to pug-code-gen.
doctype	Custom doctypes WILL be allowed as a plugin to pug-code-gen.
utils	utils.merge is now unneeded in the Pug code base. If you need it there are many excellent object merge packages out there on npm. utils.stringify has been split into a new package “js-stringify.” utils.walkAST is now “pug-walk” package.
Compiler	You should either use pug-code-gen plugins which has not been implemented yet, and will be specified in the options, or if we decide in the future that we want to allow completely overriding the code generator, do that.
Parser	You should either use pug-parser plugins which is specified in the options, or if we decide in the future that we want to allow completely overriding the parser, do that.
Lexer	You should either use pug-lexer plugins which is specified in the options, or if we decide in the future that we want to allow completely overriding the lexer, do that.
nodes	We have abandoned the approach of having a class for every node and started using duck typing with AST property type.

[TimothyGu]

Added some info.

[ForbesLindesay]

We're still adding a default extension of .pug if the filename does not contain a . (see: https://github.com/pugjs/pug/blob/610972b2cedad7861ed9a447792112559615b4c3/lib/index.js#L53-L63). This means that we do not support importing files without an extension, but that's never come up as a feature request. We could consider deprecating it, but should add a warning if we do.

[TimothyGu]

Oops. Thanks for noticing it.

[tjconcept]

Context: I am currently upgrading a project from Jade to the newest Pug, and I am just dumping whatever bites me on the way here.

• Removing the CLI from this package (so I had to change jade to pug-cli in my package.json)
• Removing the --hierarchy option

[TimothyGu]

@tjconcept

• Removing the CLI from this package (so I had to change jade to pug-cli in my package.json)

The CLI was removed in jade@1.11.0 also, I believe.

• Removing the --hierarchy option

That's true. I might just make it a noop.