npm:@seletskiy/plugin-pug

README

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

You can disable code formatting for a particular code block by adding  before ```pug.

Pug code with custom formatting:

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

Prettified code:

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

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"

Prettier Options

printWidth
Currently not very accurate, but works

semi
If you want to configure different semi for pug than for js code, you can use prettier's override.

{
  "semi": false,
  "overrides": [
    {
      "files": "*.pug",
      "options": {
        "parser": "pug",
        "semi": true
      }
    }
  ]
}

singleQuote
If you want to configure different quotes for pug than for js code, you can use prettier's override.

{
  "singleQuote": true,
  "overrides": [
    {
      "files": "*.pug",
      "options": {
        "parser": "pug",
        "singleQuote": false
      }
    }
  ]
}

tabWidth
Use spaces for indentation
useTabs
Use tab for indentation Overrides tabWidth

prettier-pug specific options

These are specific options only for prettier-pug
They should be set via Prettier's overrides option

attributeSeparator
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)
closingBracketPosition
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")
```
commentPreserveSpaces
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

The definitions for these options can be found in src/options/index.ts

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

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.

Usage no npm install needed!