postcss/docs/README.md

Documentation

• PostCSS Architecture

  • Overview
  • Workflow
  • Core Structures
  • API Reference

• PostCSS Plugins

  • Control
  • Packs
  • Future CSS Syntax
  • Fallbacks
  • Language Extensions
  • Colors
  • Images and Fonts
  • Grids
  • Optimizations
  • Shortcuts
  • Others
  • Analysis
  • Reporters
  • Fun

• PostCSS and Source Maps

• How to Write Custom Syntax

  • Syntax
  • Parser
    • Main Theory
    • Performance
    • Node Source
    • Raw Values
    • Tests
  • Stringifier
    • Main Theory
    • Builder Function
    • Raw Values
    • Tests

• Writing a PostCSS Plugin

  • Links
  • Step 1: Create an idea
  • Step 2: Create a project
  • Step 3: Find nodes
  • Step 4: Change nodes
  • Step 5: Fight with frustration
  • Step 6: Make it public

Guidlines

• PostCSS Plugin Guidelines

  • API
    • 1.1 Clear name with postcss- prefix
    • 1.2. Do one thing, and do it well
    • 1.3. Do not use mixins
    • 1.4. Keep postcss to peerDependencies
    • 1.5. Set plugin.postcssPlugin with plugin name
  • Processing
    • 2.1. Plugin must be tested
    • 2.2. Use asynchronous methods whenever possible
    • 2.3. Use fast node’s scanning
    • 2.4. Set node.source for new nodes
    • 2.5. Use only the public PostCSS API
  • Dependencies
    • 3.1. Use messages to specify dependencies
  • Errors
    • 4.1. Use node.error on CSS relevant errors
    • 4.2. Use result.warn for warnings
  • Documentation
    • 5.1. Document your plugin in English
    • 5.2. Include input and output examples
    • 5.3. Maintain a changelog
    • 5.4. Include postcss-plugin keyword in package.json

• PostCSS Runner Guidelines

  • API
    • 1.1. Accept functions in plugin parameters
  • Processing
    • 2.1. Set from and to processing options
    • 2.2. Use only the asynchronous API
    • 2.3. Use only the public PostCSS API
    • 3.1. Rebuild when dependencies change
  • Output
    • 4.1. Don’t show JS stack for CssSyntaxError
    • 4.2. Display result.warnings()
    • 4.3. Allow the user to write source maps to different files
  • Documentation
    • 5.1. Document your runner in English
    • 5.2. Maintain a changelog
    • 5.3. postcss-runner keyword in package.json
    • 5.4. Keep postcss to peerDependencies