/postcss-markdown

PostCSS Syntax for parsing Markdown

Primary LanguageJavaScriptMIT LicenseMIT

PostCSS Markdown Syntax

NPM license NPM version NPM downloads NPM downloads NPM downloads Build Status

PostCSS syntax for parsing Markdown

Getting Started

First thing's first, install the module:

npm install postcss-markdown --save-dev

If you want support SCSS/SASS/LESS/SugarSS syntax, you need to install the corresponding module.

Use Cases

const postcss = require("postcss");
const syntax = require("postcss-markdown")({
    // Enable support for HTML (default: true)
    htmlInMd: true,
    // syntax for parse scss (non-required options)
    scss: require("postcss-scss"),
    // syntax for parse less (non-required options)
    less: require("postcss-less"),
    // syntax for parse css blocks (non-required options)
    css: require("postcss-safe-parser"),
});
const autoprefixer = require("autoprefixer");
postcss([autoprefixer])
    .process(source, { syntax: syntax })
    .then(function (result) {
        // An alias for the result.css property. Use it with syntaxes that generate non-CSS output.
        result.content;
    });

input:

# title

```css
::placeholder {
    color: gray;
}
```

output:

# title

```css
::-moz-placeholder {
    color: gray;
}
:-ms-input-placeholder {
    color: gray;
}
::placeholder {
    color: gray;
}
```

If you want support SCSS/SASS/LESS/SugarSS syntax, you need to install these module:

Advanced Use Cases

Options

const options = {
    rules: [
        {
            // custom language
            test: /^postcss$/i,
            lang: "scss",
        },
        {
            // custom language
            test: /^customcss$/i,
            lang: "custom",
        },
    ],

    // custom parser for CSS (using `postcss-safe-parser`)
    css: "postcss-safe-parser",
    // custom parser for SASS (PostCSS-compatible syntax.)
    sass: require("postcss-sass"),
    // custom parser for SCSS (by module name)
    scss: "postcss-scss",
    // custom parser for LESS (by module path)
    less: require.resolve("./node_modules/postcss-less"),
    // custom parser for SugarSS
    sugarss: require("sugarss"),
    // custom parser for custom language
    custom: require("postcss-custom-syntax"),
};
const syntax = require("postcss-markdown")(options);

Turning PostCSS off from within your Markdown

PostCSS can be temporarily turned off by using special comments in your Markdown. For example:

<!-- postcss-ignore -->
```css
a {
    color: red;
}
```

Linting with Stylelint

The main use case of this plugin is to apply linting with Stylelint to CSS (and CSS-like) code blocks in markdown file.

You can use it by configuring your stylelint config as follows:

{
    "overrides": [
        {
            "files": ["*.md", "**/*.md"],
            "customSyntax": "postcss-markdown"
        }
    ]
}

Editor integrations

Visual Studio Code

Use the stylelint.vscode-stylelint extension that Stylelint provides officially.

You have to configure the stylelint.validate option of the extension to check .md files, because the extension does not check the *.md file by default.

Example .vscode/settings.json:

{
  "stylelint.validate": [
      ...,
      // ↓ Add "markdown" language.
      "markdown"
  ]