Package Exports

@prettier/plugin-pug

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@prettier/plugin-pug) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Prettier Pug plugin

Intro

Prettier is an opinionated code formatter. It enforces a consistent style by parsing your code and re-printing it with its own rules that take the maximum line length into account, wrapping code when necessary.

This plugin adds support for the Pug language to Prettier.

Getting started
Usage
- Selectively ignoring automatic formatting
Configuration
- Pug versions of standard prettier options
- Additional pug-specific options
Workarounds / Known Issues
Integration with editors
Implementation details
Contributing
Credits

Getting started

Simply install prettier and @prettier/plugin-pug as your project’s npm devDependencies:

## add Prettier and its Pug plugin to project’s dev dependencies
npm install --dev prettier @prettier/plugin-pug
## or
yarn add --dev prettier @prettier/plugin-pug

Usage

## format all pug files in your project
npx prettier --write "**/*.pug"
## or
yarn prettier --write "**/*.pug"

Selectively ignoring automatic formatting

You can disable code formatting for a particular element by adding //- prettier-ignore comments in your pug templates:

div.text( color =   "primary",  disabled  ="true"  )
//- prettier-ignore
div.text( color =   "primary",  disabled  ="true"  )
//- prettier-ignore: because of reasons
div
  div.text( color =   "primary",  disabled  ="true"  )

Prettified output:

.text(color="primary", disabled)
//- prettier-ignore
div.text( color =   "primary",  disabled  ="true"  )
//- prettier-ignore: because of reasons
div
  div.text( color =   "primary",  disabled  ="true"  )

You can also disable code formatting in Markdown for a particular ```pug block by adding  before the block:

Pug code with preserved custom formatting:

<!-- prettier-ignore -->
```pug
div.text( color =   "primary",  disabled  ="true"  )
```

Pug code with automatic formatting:

```pug
.text(color="primary", disabled)
```

Configuration

Pug versions of standard prettier options

By default, the same formatting options are used as configured through the standard prettier options. By using versions of these standard options prefixed with pug, you can override pug formatting options even when using pug embedded in other files, e.g. vue single-file components:

Name	Description
`pugBracketSpacing`	Print spaces between brackets in object literals.
`pugPrintWidth`	Specify the line length that the printer will wrap on.
`pugSemi`	Print semicolons at the ends of code statements.
`pugSingleQuote`	Use single quotes instead of double quotes. Please note that the opposite setting will be used automatically for inlined JavaScript.
`pugTabWidth`	Use spaces for indentation and specify the number of spaces per indentation-level.
`pugUseTabs`	Indent lines with tabs instead of spaces. Overrides `pugTabWidth`
`pugArrowParens`	Include parentheses around a sole arrow function parameter.

Additional pug-specific options

These additional options are specific to pug templates and can be configured in your global .prettierrc file:

Name	Type	Default	Description
`pugAttributeSeparator`	choice	`'always'`	Change when attributes are separated by commas in tags. `'always'` -> Always separate attributes with commas. Example: `button(type="submit", (click)="play()", disabled)` `'as-needed'` -> Only add commas between attributes where required. Example: `button(type="submit", (click)="play()" disabled)` `'none'` -> Never add commas between attributes. Example: `button(type="submit" @click="play()" :style="style" disabled)` Please note that while this option will process Angular syntax (e.g. `(click)="play()"`), the resulting pug file will throw a syntax error when parsed: `Syntax Error: Assigning to rvalue`
`pugClosingBracketPosition`	choice	`'new-line'`	Position of closing bracket of attributes. `'new-line'` -> Closing bracket ends with a new line. Example: input( type="text", value="my_value", name="my_name", alt="my_alt", autocomplete="on" ) `'last-line'` -> Closing bracket remains with last attribute's line. Example: input( type="text", value="my_value", name="my_name", alt="my_alt", autocomplete="on")
`pugCommentPreserveSpaces`	choice	`'keep-all'`	Change behavior of spaces within comments. `'keep-all'` -> Keep all spaces within comments. Example: `// ___this _is __a __comment_` `'keep-leading'` -> Keep leading spaces within comments. Example: `// ___this is a comment` `'trim-all'` -> Trim all spaces within comments. Example: `// this is a comment`
`pugSortAttributesBeginning` `pugSortAttributesEnd`	array	`[]`	Sort attributes by regex patterns to the beginning or the end. Example This feature was planned since `1.2.0`, but it was always a bit unstable and opinionated. If there are any bugs, please report them.
`pugSortAttributes`	choice	`'as-is'`	Sort attributes that are not on beginning and end patterns. `'as-is'` -> Keep the attributes untouched. Example: `Foo(a c d b)` `'asc'` -> Sort attributes ascending. Example: `Foo(a b c d)` `'desc'` -> Sort attributes descending. Example: `Foo(d c b a)`
`pugWrapAttributesThreshold`	choice	`-1`	Define the maximum amount of attributes that an element can appear with on one line before it gets wrapped. `-1` -> Only wrap attributes as needed. Example: input(type="text") input(type="text", value="my_value", name="my_name") `0` -> Always wrap attributes. Example: input( type="text" ) input( type="text", value="my_value", name="my_name" ) `1` -> Allow one unwrapped attribute, wrap two and more. Example: input(type="text") input( type="text", value="my_value", name="my_name" ) `2 .. Infinity` -> Same as above, just with different thresholds.
`pugWrapAttributesPattern`	array	`[]`	Define a regex pattern to match attributes against that should always trigger wrapping.
`pugSingleFileComponentIndentation`	boolean	`false`	Indent pug in template tags in single file components such as from vue or svelte.
`pugEmptyAttributes`	choice	`'as-is'`	Change behavior of boolean attributes. `'as-is'` -> Nothing is changed. Example: `foo(a, b="", c)` `'none'` -> Every attribute with empty quotes will have them removed. Example: `foo(a, b, c)` `'all'` -> Every boolean attribute will be expressed with empty quotes. Example: `foo(a="", b="", c="")`
`pugEmptyAttributesForceQuotes`	array	`[]`	Define a list of patterns for attributes that will be forced to have empty quotes even with "none" selected.
`pugClassNotation`	choice	`'literal'`	Define how classes should be formatted. `'literal'` -> Forces all valid classes to be printed as literals. Example: `foo.bar.baz` ~~`'attribute'` -> Forces all classes to be printed as attributes.~~ this option is still in progress Example: `foo(class="bar baz")` `'as-is'` -> Disables class formatting. Example: `foo.bar(class="baz")`
`pugIdNotation`	choice	`'literal'`	Define how ids should be formatted. `'literal'` -> Forces all valid ids to be printed as literals. Example: `foo#bar` ~~`'attribute'` -> Forces all ids to be printed as attributes.~~ this option is still in progress Example: `foo(id="bar")` `'as-is'` -> Disables id formatting. Example: `foo(id="bar")`

Workaround / Known Issue

There are some code examples that are not formatted well with this plugin and can damage your code.
But there are workarounds for it. These generate even better pug code!

Example

Issue 114

If you have tags at the top/root that are indented, they will lose indentation due to a technical limitation of pug.
Please check these before committing after running this plugin for the first time and fix them manually.

Integration with editors

If you are using a text editor that supports Prettier integration (e.g. Atom), you can have all Prettier perks for your Pug code too!

Use VSCode extension to get support for VSCode.

In order to get @prettier/plugin-pug working in projects that do not have local npm dependencies, you can install this plugin globally:

npm install --global prettier @prettier/plugin-pug

In this case, you might need to check the settings of your editor’s Prettier extension to make sure that a globally installed Prettier is used when it is not found in project dependencies (i.e. package.json).

Nevertheless, it is recommended to rely on local copies of prettier and @prettier/plugin-pug as this reduces the chance of formatting conflicts between project collaborators. This may happen if different global versions of Prettier or its Pug plugin are used.

Installing @prettier/plugin-pug either locally or globally may require you to restart the editor if formatting does not work right away.

Implementation details

This plugin is written in TypeScript and its quality is maintained using Prettier and Jest.

Contributing

If you’re interested in contributing to the development of Prettier for Pug, you can follow the CONTRIBUTING guide from Prettier, as it all applies to this repository too.

To run @prettier/plugin-pug locally:

Clone this repository.
Execute yarn install.
Execute yarn lint to make sure that the code passes formatting and linting.
Execute yarn test to make sure that TypeScript successfully compiles into JavaScript and and all unit tests pass.

Credits

This project was inspired by https://github.com/gicentre/prettier-plugin-elm.
Many thanks also to @j-f1, @lipis and @azz for the help in transferring this repository to the prettier organization.

Thanks to @Peilonrayz, who gave me the idea to rewrite the printer into a class and thus make the code a lot more maintainable.

Thanks to @lehni and @SkyaTura for the massive contribution and the introduction of many new features into the project.