Skip to main content

A CLI for compiling SCSS files to CSS, and associated pre-commit hook.

Project description

scss-compile

A CLI for compiling SCSS files to CSS, and associated pre-commit hook.

This CLI is a small wrapper around libsass-python, which also aims to be compatible with pre-commit, and provide a pre-commit hook.

NOTE: The package in on alpha release, but looks to be working as intended, and will be trialled in sphinx-panels, and then sphinx-book-theme.

Installation

To use directly as a CLI:

pip install scss-compile
scss-compile --help

To use via pre-commit:

Add to your .pre-commit-config.yaml

-   repo: https://github.com/executablebooks/scss-compile
    rev: v0.1.0
    hooks:
      - id: scss-compile
        args: [--config=config.yml] # optional

Configuration

You can can configure the compilation directly via the CLI or using a configuration file (simply replace - with _):

$ scss-compile --help
Usage: scss-compile [OPTIONS] [PATHS]...

  Compile all SCSS files in the paths provided.

  For directories; include all non-partial SCSS files, and for files; if
  partial, include all adjacent, non-partial, SCSS files.

Options:
  --recurse / --no-recurse        For directories, include files in sub-
                                  folders.  [default: True]

  -d, --partial-depth INTEGER     For partial files (starting '_') include all
                                  SCSS files up 'n' parent folders  [default:
                                  0]

  -s, --stop-on-error             Stop on the first compilation error.
  -e, --encoding TEXT             [default: utf8]
  -f, --output-format [nested|expanded|compact|compressed]
                                  [default: compressed]
  -m, --sourcemap                 Output source map.
  -h, --hash-filenames            Add the content hash to filenames:
                                  <filename><hash-prefix><hash>.css (old
                                  hashes will be removed).

  --hash-prefix TEXT              Prefix to use for hashed filenames.
                                  [default: #]

  -t, --translate TEXT            Source to output path translations, e.g.
                                  'src/scss:dist/css' (can be used multiple
                                  times)

  -p, --precision INTEGER         precision for numbers.  [default: 5]
  -q, --quiet                     Remove stdout logging.
  -v, --verbose                   Increase stdout logging.
  --exit-code INTEGER             Exit code when files changed.  [default: 2]
  --no-git                        Do not add new files to a git index.
  --test-run                      Do not delete/create any files.
  --config FILE                   Read default configuration from a file
                                  (allowed extensions: .json, .toml, .yml,
                                  .yaml.)

  --help                          Show this message and exit.

--config can point to any of three file-formats:

config.json:

{
  "scss-compile": {
    "precision": 5,
    "sourcemap": true,
    "hash_filenames": true,
    "output_format": "compressed",
    "partial_depth": 1,
    "translate": ["tests/example_sass:tests/output_css"]
  }
}

config.toml:

[scss-compile]
precision = 5
sourcemap = true
hash_filenames = true
output_format = "compressed"
partial_depth = 1
translate = ["tests/example_sass:tests/output_css"]

config.yml/config.yaml:

scss-compile:
  precision: 5
  sourcemap: true
  hash_filenames: true
  output_format: compressed
  partial_depth: 1
  translate: ["tests/example_sass:tests/output_css"]

Usage

If you simply specify a normal SCSS file, then the CSS file will be output in the same folder:

$ scss-compile scss/file.scss
scss/
    file.scss
    file.css

If you use the sourcemap option, then a sourcemap will also be output, and a sourceMappingURL comment added to the CSS:

$ scss-compile scss/file.scss --sourcemap
scss/
    file.scss
    file.css
    file.scss.map.json

If you use the hash_filenames option, then the CSS filename will include the content hash (and any existing file with a different hash will be removed):

$ scss-compile scss/file.scss -- hash-filenames
scss/
    file.scss
    file#beabd761a3703567b4ce06c9a6adde55.css

If you specify a partial file, i.e. ones beginning _ used via @import and @use, then all "normal" SCSS files in that folder will be compiled. If you also use the partial-depth option, then files in parent folders will also be compiled.

$ scss-compile scss/imports/_partial.scss -- partial-depth=1
scss
   /imports
       _partial.scss
    file.scss
    file.css

If you set the --translate option, then the output files will be "translated" to the specified output path (which will be created if it does not yet exist):

$ scss-compile scss/file.scss --translate "src/scss:dist/css" --sourcemap
src/scss/
    file.scss
dist/css/
    file.css
    file.scss.map.json

If you specify a directory, then it will first find all SCSS files in that directory, and recursive sub-folders (unless --no-recurse is used), then treat each individual file as above.

Development

To run the tests:

pip install tox
tox -e py37

To test out the CLI:

tox -e py37-cli

For code style:

pip install pre-commit
pre-commit run --all

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

scss-compile-0.1.3.tar.gz (7.5 kB view hashes)

Uploaded Source

Built Distribution

scss_compile-0.1.3-py3-none-any.whl (7.6 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page