SCSS include plugin for asciidoctor-extender

This plugin allows for the inclusion of commented scss files in asciidoc. Mainly intended for use with variable files and in-file documentation.

Important notice: This is a plugin for the asciidoctor.js-extender project.

If you wish to submit a bug, contribute or request a feature please follow the guides at the end of this document.

Installation

To include the library in your project run the following command:

npm install -S @asciidoctor-extender/adoc-ext-include-scss

Configuration

In order to use the plugin with the asciidoctor.js-extender project add the plugin to the configuration:

{
  "extensions": {
    "include": [
      "@asciidoctor-extender/adoc-ext-include-scss",
      ...
    ]
  },
  ...
}

Usage

To create a description block use H[ 1-7 ] followed by the header title and a description.

//@H2 Variables
//@description This file contains the base variables for the application.

To create a block of variables with descriptions use:

//@description The base color for all text
$color-text: rgba(0, 0, 0, 1);

//@description The color used for warning text
$color-text--warning: rgba(255, 150, 60, 1);

//@description The color used for error text
$color-text--error: rgba(255, 0, 0, 1);

Which renders as:

| Name | Value | Description | |:--- |:----- |:----------- | | color-text | rgba(0, 0, 0, 1) | The base color for all text | | color-text—​warning | rgba(255, 150, 60, 1) | The color used for warning text | | color-text—​error | rgba(255, 0, 0, 1) | The color used for error text |

Seperate with two empty lines to break up the block and start a new block:

//@description The base color for all text
$color-text: rgba(0, 0, 0, 1);

//@description The color used for warning text
$color-text--warning: rgba(255, 150, 60, 1);


//@description The color used for error text
$color-text--error: rgba(255, 0, 0, 1);

Which renders as:

| Name | Value | Description | |:--- |:----- |:----------- | | color-text | rgba(0, 0, 0, 1) | The base color for all text | | color-text—​warning | rgba(255, 150, 60, 1) | The color used for warning text |

| Name | Value | Description | |:--- |:----- |:----------- | | color-text—​error | rgba(255, 0, 0, 1) | The color used for error text |

Registering issues

Should something be awry please feel free to register a bug by creating an issue labeled "bug" with a clear description of what fails, what is expected and steps to reproduce the error.

Contributing

To contribute to this library you can fork the library, implement the feature and create a pull request. Then create an issue labeled "Contribution" with a clear description of the feature and a reference to the pull request.

Requesting new features

In order to request a new feature please open a new issue labeled "Feature request" and a clear description of the functionality that is requested.