postcss-markdown

PostCSS Markdown Syntax

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.

• SCSS: postcss-scss
• SASS: postcss-sass
• LESS: postcss-less
• SugarSS: sugarss
• Stylus: postcss-styl

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:

• SCSS: postcss-scss
• SASS: postcss-sass
• LESS: postcss-less
• SugarSS: sugarss
• Stylus: postcss-styl

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"
  ]

Similar packages

Other packages similar to postcss-markdown

postcss-html

The postcss-html package is similar to postcss-markdown but is designed for processing CSS within HTML files. It allows you to apply PostCSS transformations to CSS code embedded in HTML, making it suitable for projects where HTML is the primary format.

postcss-js

The postcss-js package allows you to use PostCSS with JavaScript objects instead of CSS strings. While it serves a different purpose than postcss-markdown, it similarly extends PostCSS's capabilities to non-standard CSS formats.