From bcf4112946fa2b635d3516ca63b4ec5904958c38 Mon Sep 17 00:00:00 2001 From: Victor Bocharsky Date: Fri, 11 Oct 2024 14:33:18 +0200 Subject: [PATCH] Improve the docs (#77) Add more information about the bundle's behaviour after #76 --- doc/index.rst | 52 +++++++++++++++++++++++++++++++++++---------------- 1 file changed, 36 insertions(+), 16 deletions(-) diff --git a/doc/index.rst b/doc/index.rst index 47b1536..4dd7643 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -4,7 +4,8 @@ Sass For Symfony! This bundle makes it easy to use Sass with Symfony's AssetMapper Component (no Node required!). -- Automatically downloads the correct Sass binary +- Automatically detects the Sass binary installed in the system +- Automatically downloads the correct Sass binary if it's not detected in the system - Adds a ``sass:build`` command to build and watch your Sass changes .. tip:: @@ -25,7 +26,7 @@ Install the bundle: Usage ----- -Start by writing your first Sass file ``assets/styles/app.scss``, and let's add some basic style +Start by writing your first Sass file ``assets/styles/app.scss``, and let's add some basic style: .. code-block:: scss @@ -37,7 +38,7 @@ Start by writing your first Sass file ``assets/styles/app.scss``, and let's add background: $red; } -Then point your styles in your template +Then point your styles in your template: .. code-block:: html+twig @@ -79,16 +80,21 @@ to be started whenever you run ``symfony server:start``: How Does it Work? ----------------- -The first time you run one of the Sass commands, the bundle will download the correct Sass binary for your system into the ``bin/dart-sass`` directory. +The first time you run one of the Sass commands, the bundle will automatically try to detect +the correct Sass binary installed in the system and use it. If the binary is not found, +the bundle will automatically download the correct one for your system and put it into +the ``bin/dart-sass`` directory. -When you run ``sass:build``, that binary is used to compile Sass files into a ``var/sass/app.built.css`` file. Finally, when the contents of ``assets/styles/app.scss`` are requested, the bundle swaps the contents of that file with the contents of ``var/sass/app.built.css``. Nice! +When you run ``sass:build``, that binary is used to compile Sass files into a ``var/sass/app.built.css`` +file. Finally, when the contents of ``assets/styles/app.scss`` are requested, the bundle swaps +the contents of that file with the contents of ``var/sass/app.built.css``. Nice! Excluding Sass Files from AssetMapper ------------------------------------- Because you have ``.scss`` files in your ``assets/`` directory, when you deploy, these source files will be copied into the ``public/assets/`` directory. To prevent that, -you can exclude them from asset mapper: +you can exclude them from AssetMapper: .. code-block:: yaml # config/packages/asset_mapper.yaml @@ -106,11 +112,11 @@ you can exclude them from asset mapper: this *is* used in AssetMapper and its contents are swapped for the final, built CSS. -How to Get Source Sass Files for 3rd-party Libraries +How to Get Source Sass Files for 3rd-Party Libraries ---------------------------------------------------- -The easiest way to get 3rd-party Sass files is via Composer. For example, see -the section below to know how to get the source Sass files for Bootstrap. +The easiest way to get 3rd-party Sass files is via `Composer `_. For example, see +the section below to know how to get the source Sass files for `Bootstrap `_. But if you're using a library that isn't available via Composer, you’ll need to either download it to your app manually or grab it via NPM. @@ -118,7 +124,8 @@ to either download it to your app manually or grab it via NPM. Using Bootstrap Sass ~~~~~~~~~~~~~~~~~~~~ -`Bootstrap `_ is available as Sass, allowing you to customize the look and feel of your app. An easy way to get the source Sass files is via a Composer package: +`Bootstrap `_ is available as Sass, allowing you to customize +the look and feel of your app. An easy way to get the source Sass files is via a Composer package: .. code-block:: terminal @@ -169,7 +176,8 @@ When you deploy, run ``sass:build`` command before the ``asset-map:compile`` com Limitation: ``url()`` Relative Paths ------------------------------------ -When using ``url()`` inside a Sass file, currently, the path must be relative to the *root* ``.scss`` file. For example, suppose the root ``.scss`` file is: +When using ``url()`` inside a Sass file, currently, the path must be relative to the *root* ``.scss`` file. +For example, suppose the root ``.scss`` file is: .. code-block:: scss @@ -189,7 +197,8 @@ Assume there is an ``assets/images/login-bg.png`` file that you want to refer to background-image: url('../images/login-bg.png'); } -It should be possible to use ``url()`` with a path relative to the current file. However, that is not currently possible. See `this issue `_ for more details. +It should be possible to use ``url()`` with a path relative to the current file. However, that is not +currently possible. See `this issue `_ for more details. Configuration ------------- @@ -204,13 +213,14 @@ To see the full config from this bundle, run: Source Sass file ~~~~~~~~~~~~~~~~ -The main option is ``root_sass`` option, which defaults to ``assets/styles/app.scss``. This represents the source Sass file. +The main option is the ``root_sass`` option, which defaults to ``assets/styles/app.scss``. +This represents the source Sass file: .. code-block:: yaml # config/packages/symfonycasts_sass.yaml symfonycasts_sass: - root_sass: 'assets/styles/app.scss' + root_sass: 'assets/styles/app.scss' .. note:: @@ -241,7 +251,7 @@ You can configure most of the `Dart Sass CLI options