@prettier/plugin-pug

           

Prettier Pug plugin

Please note that the plugin ecosystem in Prettier is still beta, which may make @prettier/plugin-pug not ready for production use yet.

---

Plugin for Prettier to format pug code

Getting started

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

cd /path/to/project

## initialise an npm project if you haven’t done it yet
npm init
## or
yarn init

## 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
./node_modules/.bin/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 <!-- prettier-ignore --> 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)
```

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:

• 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:

• pugAttributeSeparator
  Change when attributes are separated by commas in tags.

  Choices:

  • 'always' default -> 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
  Position of closing bracket of attributes.

  Choices:

  • 'new-line' default -> 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
  Change behavior of spaces within comments.

  Choices:

  • 'keep-all' default -> 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
  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 Sort attributes that are not on beginning and end patterns.

  Choices:

  • 'as-is' default -> 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
  Define the maximum amount of attributes that an element can appear with on one line before it gets wrapped.

• pugWrapAttributesPattern
  Define a regex pattern to match attributes against that should always trigger wrapping.

  Choices:

  • -1 default -> 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.

Some workarounds

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!

Examples

Issue 53

input(onClick="methodname(\"" + variable + "\", this)")
// transforms to
input(onClick="methodname(\"\" + variable + \"\", this)")

// In most cases ES6 template strings are a good solution
input(onClick=`methodname("${variable}", this)`)

As mentioned in pugjs.org Attribute Interpolation (2.), you should prefere ES2015 template strings to simplify your attributes.

Issue 54

- const id = 42
- const collapsed = true

div(id=id, class='collapse' + (collapsed ? '' : ' show') + ' cardcontent')
// transforms to
.cardcontent(id=id, class="collapse' + (collapsed ? '' : ' show') + '")

// better write
.cardcontent.collapse(id=id, class=collapsed ? '' : 'show')
// Now your js logic is extracted from the plain logic

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 repos to the prettier orga.

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.