{"id":13852067,"url":"https://github.com/SC5/sc5-styleguide","last_synced_at":"2025-07-13T03:33:10.013Z","repository":{"id":21351797,"uuid":"24668894","full_name":"SC5/sc5-styleguide","owner":"SC5","description":"Styleguide generator is a handy little tool that helps you generate good looking styleguides from stylesheets using KSS notation","archived":false,"fork":false,"pushed_at":"2022-12-16T02:34:17.000Z","size":5818,"stargazers_count":1261,"open_issues_count":140,"forks_count":167,"subscribers_count":55,"default_branch":"master","last_synced_at":"2024-10-29T17:58:05.672Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://styleguide.sc5.io/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SC5.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-10-01T07:03:53.000Z","updated_at":"2024-09-01T15:01:25.000Z","dependencies_parsed_at":"2023-01-12T03:45:30.836Z","dependency_job_id":null,"html_url":"https://github.com/SC5/sc5-styleguide","commit_stats":null,"previous_names":[],"tags_count":91,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SC5%2Fsc5-styleguide","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SC5%2Fsc5-styleguide/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SC5%2Fsc5-styleguide/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SC5%2Fsc5-styleguide/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SC5","download_url":"https://codeload.github.com/SC5/sc5-styleguide/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225675007,"owners_count":17506272,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-04T22:00:57.487Z","updated_at":"2024-11-22T06:30:56.874Z","avatar_url":"https://github.com/SC5.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","Style Guide Generators :slot_machine:"],"sub_categories":["Editor's Draft :black_nib:"],"readme":"# SC5 style guide generator\n\n[![Build Status](https://travis-ci.org/SC5/sc5-styleguide.svg?branch=master)](https://travis-ci.org/SC5/sc5-styleguide) [![dependencies](https://david-dm.org/SC5/sc5-styleguide.svg)](https://david-dm.org/SC5/sc5-styleguide) [![npm version](https://badge.fury.io/js/sc5-styleguide.svg)](http://badge.fury.io/js/sc5-styleguide)\n\n## Looking for a maintainer\n\n**If you would like to maintain the project, create an issue and tell a few words about yourself.**\n\nStyle guide generator is a handy little tool that helps you generate good looking style guides from style sheets\nusing KSS notation. It can be used as a command line utility, gulp task or Grunt task (needs grunt-gulp) with minimal effort.\n\n## Table of contents\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n\n- [Usage](#usage)\n  - [Prerequisites](#prerequisites)\n  - [With Gulp](#with-gulp)\n  - [With Grunt](#with-grunt)\n  - [As a command line tool](#as-a-command-line-tool)\n  - [Build options](#build-options)\n- [Documenting syntax](#documenting-syntax)\n  - [Defining an Angular directive](#defining-an-angular-directive)\n  - [Ignore parts of the style sheet from being processed](#ignore-parts-of-the-style-sheet-from-being-processed)\n  - [Wrapper markup](#wrapper-markup)\n  - [Inserted markup](#inserted-markup)\n  - [Pug (jade) markup](#pug-jade-markup)\n- [Designer tool](#designer-tool)\n- [Images, fonts and other static assets](#images-fonts-and-other-static-assets)\n- [Tips and pointers](#tips-and-pointers)\n  - [`\u003chtml\u003e` and `\u003cbody\u003e` styles](#html-and-body-styles)\n  - [Providing additional CSS](#providing-additional-css)\n  - [Providing additional JavaScript](#providing-additional-javascript)\n  - [onRendered event](#onrendered-event)\n  - [Adding new section in between](#adding-new-section-in-between)\n- [Demo](#demo)\n- [Additional Info](#additional-info)\n  - [Articles, blog posts](#articles-blog-posts)\n  - [Supplementary packages](#supplementary-packages)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## Usage\n\nYou should familiarize yourself with both [KSS](https://github.com/kneath/kss)\nand [node-kss](https://github.com/kss-node/kss-node) to get yourself started.\n\nSC5 Style guide provides additions to KSS syntax which you can learn [below](#user-content-documenting-syntax).\n\n### Prerequisites\n\nThe tool should be installed onto:\n\n- Node 4.2.x\n- Node 6.9.x\n\n### With Gulp\n\nInstall plugin locally:\n\n```bash\nnpm install sc5-styleguide --save-dev\n```\n\nThe Gulp plugin contains two functions that requires different set of file streams:\n\n`generate()`: All unprocessed styles containing the KSS markup and style variables. This will process the KSS markup and collects variable information.\n\n`applyStyles()`: Pre-processed/compiled style sheets. This will create necessary pseudo styles and create the actual style sheet to be used in the styleguide.\n\nThe following code shows complete example how to use styleguide with gulp-sass and with gulp watch.\n\n```js\nvar gulp = require('gulp');\nvar styleguide = require('sc5-styleguide');\nvar sass = require('gulp-sass');\nvar outputPath = 'output';\n\ngulp.task('styleguide:generate', function() {\n  return gulp.src('*.scss')\n    .pipe(styleguide.generate({\n        title: 'My Styleguide',\n        server: true,\n        rootPath: outputPath,\n        overviewPath: 'README.md'\n      }))\n    .pipe(gulp.dest(outputPath));\n});\n\ngulp.task('styleguide:applystyles', function() {\n  return gulp.src('main.scss')\n    .pipe(sass({\n      errLogToConsole: true\n    }))\n    .pipe(styleguide.applyStyles())\n    .pipe(gulp.dest(outputPath));\n});\n\ngulp.task('watch', ['styleguide'], function() {\n  // Start watching changes and update styleguide whenever changes are detected\n  // Styleguide automatically detects existing server instance\n  gulp.watch(['*.scss'], ['styleguide']);\n});\n\ngulp.task('styleguide', ['styleguide:generate', 'styleguide:applystyles']);\n```\n\nThis approach gives flexibility to use any preprocessor. For example, you can freely replace gulp-sass with gulp-ruby-sass. However, please notice that variable parsing works only for Sass, SCSS and Less files.\n\nIf you do not use preprocessor you can directly pipe CSS files to `applyStyles()`.\n\nSee [Build options](#build-options) section for complete documentation of different options.\n\n### With Grunt\n\nFor projects using Grunt, install the plugin, Gulp and the `grunt-gulp` bridge.\n\n```bash\nnpm install sc5-styleguide gulp grunt-gulp --save-dev\n```\n\nThen you are able to use the same gulp task inside you `Gruntfile`:\n\n```js\nvar gulp = require('gulp'),\n  styleguide = require('sc5-styleguide');\n\ngrunt.initConfig({\n  pkg: grunt.file.readJSON('package.json'),\n  gulp: {\n    'styleguide-generate': function() {\n      var outputPath = 'output';\n      return gulp.src([''])\n        .pipe(styleguide.generate({\n            title: 'My Styleguide',\n            server: true,\n            rootPath: outputPath,\n            overviewPath: 'README.md'\n          }))\n        .pipe(gulp.dest(outputPath));\n    },\n    'styleguide-applystyles': function() {\n      return gulp.src('main.scss')\n        .pipe(styleguide.applyStyles())\n        .pipe(gulp.dest('output'));\n    }\n  },\n\n  watch: {\n    scss: {\n      files: '**/*.scss',\n      tasks: ['scss', 'gulp:styleguide-generate', 'gulp:styleguide-applystyles']\n    }\n  }\n});\n\ngrunt.loadNpmTasks('grunt-gulp');\n\ngrunt.registerTask('default', ['gulp:styleguide-generate', 'gulp:styleguide-applystyles', 'watch']);\n```\n\nWhen using Grunt, we recommend processing styles in Grunt tasks as you do for your main application and pass\nthe resultant CSS into styleguide's Gulp tasks.\n\nFor more specific documentation see the next section.\n\n### As a command line tool\n\nThis way of usage is not recommended, as it does not help as much with introduction of the styleguide into the day-to-day development process.\n\nInstall plugin globally:\n\n```bash\nnpm install -g sc5-styleguide\n```\n\nStyleguide command line tool requires two sets of source files:\n\n`--kss-source`: Unprocessed files containing the KSS markup and Less/Sass variables\n\n`--style-source` Pre-processed/compiled style sheets to be used in the styleguide\n\nExample usage:\n\n```bash\nstyleguide --kss-source \"sass/*.scss\" --style-source \"public/*.css\" --output styleguide --watch --server\n```\n\nYou need to either specify a single directory or you can specify one or more source directories with one or more --kss-source flags.\n\n```bash\nstyleguide --kss-source \"style/*.scss\" --style-source \"public/*.css\" --output styleguide --watch --server\n```\n\nOther options parameters are defined in the [Build options](#build-options) section.\n\n### Build options\n\nCLI and gulp options accept identically named parameters\n\n\u003ca name=\"option-title\"\u003e\u003c/a\u003e\n**title** (string, optional)\n\nThis string is used as a page title and in the page header\n\n\u003ca name=\"option-favicon\"\u003e\u003c/a\u003e\n**favIcon** (string, optional)\n\nThis enables to replace the default SC5 favicon. It takes path as a string.\n\n\u003ca name=\"option-extraHead\"\u003e\u003c/a\u003e\n**extraHead** (array or string, optional)\n\nThese HTML elements are injected inside the style guide `head` tag.\n\n\u003ca name=\"option-sideNav\"\u003e\u003c/a\u003e\n**sideNav** (boolean, optional, default: false)\n\nEnables side navigation. When this option parameter is enabled, styleguide will switch to side navbar.\n\n\u003ca name=\"option-showReferenceNumbers\"\u003e\u003c/a\u003e\n**showReferenceNumbers** (boolean, optional, default: false)\n\nWhen this option parameter is enabled, style guide will show reference numbers on navigation, headings and designer tool.\n\n\u003ca name=\"option-includeDefaultStyles\"\u003e\u003c/a\u003e\n**includeDefaultStyles** (boolean, optional, default: true)\n\nInclude/exclude default styles.\n\n\u003ca name=\"option-showMarkupSection\"\u003e\u003c/a\u003e\n**showMarkupSection** (boolean, optional, default: true)\n\nShow/hide Markup section.\n\n\u003ca name=\"option-hideSubsectionsOnMainSection\"\u003e\u003c/a\u003e\n**hideSubsectionsOnMainSection** (boolean, optional, default: false)\n\nThis option enables to prevent loading of subsections.\n\n\u003ca name=\"option-beforeBody\"\u003e\u003c/a\u003e\n**beforeBody** (array or string, optional)\n\nThese HTML elements are injected inside the style guide `\u003cbody\u003e` tag, before any other content.\n\n\u003ca name=\"option-afterBody\"\u003e\u003c/a\u003e\n**afterBody** (array or string, optional)\n\nThese HTML elements are injected inside the style guide `\u003cbody\u003e` tag, after any other content.\n\n\u003ca name=\"option-afterSections\"\u003e\u003c/a\u003e\n**afterSections** (array or string, optional)\n\nThese HTML elements are injected inside the style guide `.sg-body` section, after any other content.\n\n\u003ca name=\"option-commonClass\"\u003e\u003c/a\u003e\n**commonClass** (string or array of strings, optional)\n\nThe provided classes are added to all preview blocks in the generated style guide.\nThis option is useful if you have some namespace classes that should to be added to every block, but you do not want to add it to every example section's markup.\n\n\u003ca name=\"option-server\"\u003e\u003c/a\u003e\n**server** (boolean, optional)\n\nEnable built-in web-server. To enable Designer tool the style guide must be served with the built-in web server.\nThe server also has the ability to refresh changed styles or KSS markup without doing a full page reload.\n\n\u003ca name=\"option-port\"\u003e\u003c/a\u003e\n**port** (number, optional)\n\nPort of the server. Default is 3000.\n\n\u003ca name=\"option-disableServerLog\"\u003e\u003c/a\u003e\n**disableServerLog** (boolean, optional)\n\nDisables embedded server log.\n\n\u003ca name=\"option-rootPath\"\u003e\u003c/a\u003e\n**rootPath** (string, optional)\n\nServer root path. This must be defined if you run the built-in server via gulp or Grunt task.\nPoint to the same path as the style guide output folder.\n\nNote: This option is not needed when running styleguide via the CLI.\n\n\u003ca name=\"option-appRoot\"\u003e\u003c/a\u003e\n**appRoot** (string, optional)\n\nDefine the `appRoot` parameter if you are hosting the style guide from a directory other than the root directory of\nthe HTTP server. If the style guide is hosted at `http://example.com/styleguide` the appRoot should be `styleguide`.\n\nWhen using the build as a subdirectory of your application, tune your server to resolve all the paths to that subdirectory.\nThis allows Angular to deal with the routing. However, the static files should be resolved as they are stored.\n\n\u003ca name=\"option-styleVariables\"\u003e\u003c/a\u003e\n**styleVariables** (string, optional)\n\nBy default variable definitions are searched from every file passed in gulp.src. styleVariables parameter could be used to filter from which files variables are loaded.\n\n\u003ca name=\"option-disableEncapsulation\"\u003e\u003c/a\u003e\n**disableEncapsulation** (boolean, optional, default: false)\n\nDisable Shadow DOM encapsulation. When this option parameter is enabled, all styles are defined in page head and markup examples are not encapsulated using Shadow DOM.\n\n\u003ca name=\"option-disableHtml5Mode\"\u003e\u003c/a\u003e\n**disableHtml5Mode** (boolean, optional, default: false)\n\nDisable HTML5 URL mode. When this option parameter is enabled, style guide will use hash bang URLs instead of HTML5 history API. This is useful when hosting static style guides.\n\n\u003ca name=\"option-basicAuth\"\u003e\u003c/a\u003e\n**basicAuth** (object, optional, default: null)\n\nProtect server with basic HTTP authentication.\n\n```js\nbasicAuth: {\n  username: 'username',\n  password: 'password'\n}\n```\n\n\u003ca name=\"option-readOnly\"\u003e\u003c/a\u003e\n**readOnly** (boolean, optional, default: false)\n\nDisable variable saving from web interface.\n\n\u003ca name=\"option-customColors\"\u003e\u003c/a\u003e\n**customColors** (string, optional)\n\nPath to file that defines custom UI color overrides using PostCSS variables. See all possible variables [here](https://github.com/SC5/sc5-styleguide/blob/master/lib/app/css/_styleguide_variables.css).\n\nInternal styles could be overridden by defining new styles inside the `styleguide_custom_styles` mixin. This mixin is added to the end of the application style sheet.\n\nYou can define your own styles with\n\n```css\n@define-mixin styleguide_custom_styles {\n  /* Define your styles here */\n}\n```\n\nPostCSS configuration supports mixins, nesting, variables, media queries.\n\n\u003ca name=\"option-parsers\"\u003e\u003c/a\u003e\n**parsers** (object, optional)\n\ndefault:\n\n```js\nparsers: {\n  sass: 'scss',\n  scss: 'scss',\n  less: 'less',\n  postcss: 'postcss'\n}\n```\n\nStyleguide tries to guess which parser to use when parsing variable information from style sheets. The object key defines the file extension to match and the value refers to the parser name. There are three parsers available: `scss`, `less` and `postcss`.\n\nFor example, to parse all .css files using postcss parser, following configuration could be used:\n\n```js\n{\n  css: 'postcss'\n}\n```\n\n\u003ca name=\"option-styleguideProcessors\"\u003e\u003c/a\u003e\n**styleguideProcessors** (object, optional)\n\ndefault:\n\n```js\nstyleguideProcessors: {}\n```\n\nStyleguide has several processors that enrich or modify the data. For example the `sg-wrapper` replacement is done by a processor.\nYou can add your own processor to enrich the styleguide data with your own content or modifications.\nYou can also override existing functionality by overwriting the related processor.\nCurrently these processors exist by default and should not be overwritten unless you know what you are doing:\n\n```js\nstyleguideProcessors: {\n    10: replaceSectionReferences,\n    20: generateSectionWrapperMarkup\n}\n```\n\nYou can define your own processors:\n\n```js\nstyleguideProcessors: {\n  11: function(styleguide) {\n    // this will run after replaceSectionReferences\n    styleguide.sections[0].description = styleguide.sections[0].description + ' [Description from custom Processor]';\n  },\n  30: function(styleguide) {\n    // this will run after generateSectionWrapperMarkup\n  }\n}\n```\n\n\u003ca name=\"option-filesConfig\"\u003e\u003c/a\u003e\n**filesConfig** (array, optional) **(Experimental feature)**\n\nAll HTML markup sections defined in the KSS block is dynamically compiled inside the styleguide thus it is possible to use Angular directive inside the markup. These external directives are lazy loaded in the styleguide Angular application. `filesConfig` configuration parameter could be used to define lazy loaded files. Files are only required, not copied automatically. You need to make sure that files are copied inside the styleguide output directory when generating the styleguide.\n\nConfiguration array containing paths to the dependencies of the hosted application\n\n```js\nfilesConfig: [\n  {\n    \"name\": \"NameOfMainAppModule\",\n    \"files\": [\n      \"path/to/dependency-file.js\",\n      \"path/to/application-file.js\",\n      \"path/to/stylesheet.css\",\n    ],\n    \"template\": \"path/to/template-filename.html\"\n  }\n]\n```\n\nNote: When using templateUrl in directives, the template path is relative to style guide index.html, not the hosted application root.\n\n**additionalNgDependencies** (array or string, optional)\n\nSome angular libraries (such as angular-material) can't be lazy loaded after bootstrapping.\nYou can use the additionalNgDependencies property to inject additional angular\ndependencies to be bootstrapped by the style guide app.\n\nYou can pass either a string (if you only have one dependency to add) or\nan array of strings. The string(s) should be the same dependencies you would\npass when bootstrapping dependencies in your own modules.\n\nWhen using this property, you should also specify an afterBody or extraHead\nconfig in order to make sure the dependencies are loaded by the browser before\nthey are bootstrapped.\n\nHere's an example showing how to use angular-material:\n\n```js\nadditionalNgDependencies: ['ngMaterial']\nextraHead: '\n  \u003clink rel=\"stylesheet\" href=\"/angular-material/angular-material.css\"\u003e\n'\nafterBody: '\n  \u003cscript src=\"/angular-aria/angular-aria.js\"\u003e\u003c/script\u003e\n  \u003cscript src=\"/angular-messages/angular-messages.js\"\u003e\u003c/script\u003e\n  \u003cscript src=\"/angular-material/angular-material.js\"\u003e\u003c/script\u003e\n'\n```\n\n## Documenting syntax\n\nDocument your CSS components with [KSS](http://warpspire.com/kss/)\n\n### Defining an Angular directive\n\nIf your components can be rendered with Angular directives, you can define them in KSS markup and so avoid copy-pasting\nin the `markup` field. This is how you can instruct the style guide to use Angular:\n\n```js\n// Test directive\n//\n// markup:\n// \u003cdiv sg-test-directive\u003eIf you see this something is wrong\u003c/div\u003e\n//\n// sg-angular-directive:\n// name: NameOfMainAppModule\n// template: path/to/template-filename.html\n// file: path/to/application-file.js\n//\n// Styleguide 1.2.3\n```\n\nIt is possible to define several files, so you can attach all the needed dependencies:\n\n```js\n// sg-angular-directive:\n// name: NameOfMainAppModule\n// template: path/to/template-filename.html\n// file: path/to/application-file.js\n// file: path/to/dependency-file.js\n// file: path/to/stylesheet.css\n```\n\nYou can also write the same with comma-syntax\n\n```js\n// sg-angular-directive:\n// name: NameOfMainAppModule\n// template: path/to/template-filename.html\n// file: path/to/application-file.js, path/to/dependency-file.js, path/to/stylesheet.css\n```\n\n### Ignore parts of the style sheet from being processed\n\nYou can ignore parts of the CSS or KSS from being processed using the following tags:\n\n```js\n// styleguide:ignore:start\nIgnored styles\n// styleguide:ignore:end\n```\n\n### Wrapper markup\n\nSometimes your component examples need a wrapper. For example:\n\n- you need to show how to use `\u003cli\u003e` element which works only with `\u003cul\u003e` container;\n- your component is not visible with white background;\n- your component needs a container with a predefined height.\n\nYou can cover such cases by adding a wrapper to a component markup. The wrapper should be defined as a custom parameter\nin the KSS documentation block:\n\n```js\n// markup:\n// \u003cli\u003e\n//   \u003ca class=\"{$modifiers}\"\u003eItem\u003c/a\u003e\n// \u003c/li\u003e\n//\n// sg-wrapper:\n// \u003cnav class=\"sg side-nav\"\u003e\n//   \u003cul\u003e\n//     \u003csg-wrapper-content/\u003e\n//   \u003c/ul\u003e\n// \u003c/nav\u003e\n```\n\nThe `\u003csg-wrapper-content/\u003e`\ninside shows where to place an example.\n\nWrappers can be used for fixes like this:\n\n```js\n// markup:\n// \u003cdiv class=\"my-component\"\u003eThis is a white component\u003c/div\u003e\n//\n// sg-wrapper:\n// \u003cdiv style=\"background-color: grey;\"\u003e\n//   \u003csg-wrapper-content/\u003e\n// \u003c/div\u003e\n```\n\nThe modifiers get the same wrapper as their parent section.\n\n**Wrappers are inheritable.** A wrapper of a parent section is inherited by its children sections. This means that the\nfollowing KSS markup\n\n```js\n// Parent section\n//\n// markup:\n// \u003cdiv class=\"parent\"\u003e\u003c/div\u003e\n//\n// sg-wrapper:\n// \u003cdiv class=\"parent-wrapper\"\u003e\n//   \u003csg-wrapper-content/\u003e\n// \u003c/div\u003e\n//\n// Styleguide 1.0\n\n...\n\n// Child section\n//\n// markup:\n// \u003cspan class=\"child\"\u003e\u003c/span\u003e\n//\n// sg-wrapper:\n// \u003cdiv class=\"parent\"\u003e\n//   \u003csg-wrapper-content/\u003e\n// \u003c/div\u003e\n//\n// Styleguide 1.1\n```\n\nwould produce a Parent section:\n\n```html\n\u003cdiv class=\"parent-wrapper\"\u003e\n  \u003cdiv class=\"parent\"\u003e\u003c/div\u003e\n\u003c/div\u003e\n```\n\nand a Child section:\n\n```html\n\u003cdiv class=\"parent-wrapper\"\u003e\n  \u003cdiv class=\"parent\"\u003e\n    \u003cspan class=\"child\"\u003e\u003c/span\u003e\n  \u003c/div\u003e\n\u003c/div\u003e\n```\n\n### Inserted markup\n\nIn the markup you can insert markup of the other sections by referring to its section number. The markup of the referred section will be inserted into the current one. You can also target specific modifiers or include all modifiers. All unknown `{$modifiers}` will be ignored. Nested insert also works.\n\n```js\n// List\n//\n// markup:\n// \u003cul\u003e\n//   \u003csg-insert\u003e1.2.1\u003c/sg-insert\u003e\n//   \u003csg-insert\u003e1.2.1-5\u003c/sg-insert\u003e to insert the 5th modifier of 1.2.1\n//   \u003csg-insert\u003e1.2.1-all\u003c/sg-insert\u003e to insert all modifiers of 1.2.1\n// \u003c/ul\u003e\n//\n// Styleguide 1.2\n\n...\n\n// List item\n//\n// markup:\n// \u003cli\u003eItem\u003c/li\u003e\n//\n// Styleguide 1.2.1\n```\n\nAt the generated website the markup is shown expanded.\n\n### Pug (jade) markup\n\nSet `enablePug: true` to enable Pug support with BEM ([bemto](https://github.com/kizu/bemto)).\nHTML supports with enabled Pug.\n\nGulpfile.js\n\n```js\ngulp.task('styleguide:generate', function() {\n  return gulp.src('*.css')\n    .pipe(styleguide.generate({\n        ...\n        enablePug: true\n        ...\n      }))\n    .pipe(gulp.dest(outputPath));\n});\n```\n\n```css\n/*\nMarkup:\n+b.block_modifier(class=\"{$modifiers}\")\n  +e.element\n*/\n```\n\n## Designer tool\n\nDesigner tool is a feature that allows editing style variable directly in the browser and saving the changes back\nto the source file. It is enabled when the [styleVariables option](#option-styleVariables) is defined and\nthe application is served with the [built-in server](#option-server).\n\nThe changed values are checked for syntax errors before saving, and if something is wrong, nothing is written to the\nsource files and an error notification is shown on the client.\n\n## Images, fonts and other static assets\n\nImages, fonts and other static assets should be copied to style guide output folder to make them accessible in the style guide. It is recommended to create a gulp or Grunt task to systematically do the copying when the style guide is generated.\n\nIf you modify your assets in gulp streams, you can add styleguide output directory as a second destination for your assets:\n\n```js\ngulp.task('images', function() {\n  gulp.src(['images/**'])\n    // Do image sprites, optimizations etc.\n    .pipe(gulp.dest(buildPath + '/images'))\n    .pipe(gulp.dest(outputPath + '/images'));\n});\n```\n\n## Tips and pointers\n\n### `\u003chtml\u003e` and `\u003cbody\u003e` styles\n\nSince each component's markup is isolated from the application styles with Shadow DOM, styles defined in\n`\u003chtml\u003e` or `\u003cbody\u003e` tags will not apply in the component previews. If you want for example to define a font that should\nalso be used in the component previews, define a css class with the font definitions and add that class to the\n[commonClass configuration option](#option-commonClass).\n\n### Providing additional CSS\n\nSometimes it is needed to apply additional CSS to the components. For example, make grid items of different colors so\nthat they could be easily seen. But such CSS should not sit together with the basic CSS of the component because it is\nnot supposed to be used in general. Obvious solution is to provide additional CSS which works in the styleguide only.\n\nAs the Styleguide shows the components isolated with Shadow DOM, any additional CSS provided with `extraHead` option\nwill not affect the components. If you want to provide additional CSS which affects the components, this code\nshould be added to the other styles when building:\n\n```js\nvar concat = require(\"gulp-concat\");\n\n...\n\ngulp.task('styleguide:applystyles', function() {\n  return gulp.src([\n      'main.scss'\n      'utils/additional.scss'\n      ])\n    .pipe(concat('all.scss'))\n    .pipe(sass({\n      errLogToConsole: true\n    }))\n    .pipe(styleguide.applyStyles())\n    .pipe(gulp.dest(outputPath));\n});\n```\n\n### Providing additional JavaScript\n\nTo provide additional JavaScript for the StyleGuide pages, define its `\u003cscript\u003e` tag in the `extraHead` parameter:\n\n```js\ngulp.task('styleguide:generate', function() {\n  return gulp.src('*.scss')\n    .pipe(styleguide.generate({\n        ...\n        extraHead: [\n          '\u003cscript src=\"/path/to/my-js-file.js\"\u003e\u003c/script\u003e'\n        ],\n        disableEncapsulation: true\n        ...\n      }))\n    .pipe(gulp.dest(outputPath));\n});\n```\n\nInclude other needed scripts, such as libraries, into the same array:\n\n```js\nextraHead: [\n  '\u003cscript src=\"https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js\"\u003e\u003c/script\u003e',\n  '\u003cscript src=\"/path/to/my-js-file.js\"\u003e\u003c/script\u003e'\n]\n```\n\nThis way you can enrich the documented components with JavaScript. Keep in mind that you need to use `disableEncapsulation` parameter to make the components visible for the parent page JavaScript (otherwise they are encapsulated with shadow DOM).\n\n### onRendered event\n\nThe components get visible onto the StyleGuide pages dynamically. This means that it takes some time to render them.\n\nIn your JavaScript you may need to operate components after they have been rendered. Catch `styleguide:onRendered` event on `window` for that:\n\n```js\n$(window).bind(\"styleguide:onRendered\", function(e) {\n  // do anything here\n  // use e.originalEvent.detail.elements to get elements\n});\n```\n\nThis is useful when you need to initialize your components. As this kind of initialization is only needed on the StyleGuide pages, you can provide it with an additional file:\n\n```js\nextraHead: [\n  '\u003cscript src=\"/path/to/my-js-file.js\"\u003e\u003c/script\u003e',\n  '\u003cscript src=\"/js/init-styleguide.js\"\u003e\u003c/script\u003e'\n]\n```\n\n### Adding new section in between\n\nYou may use `addSection` helper in order to make it easier adding a new section (or subsection) in between of the existing. It shifts reference numbers of the following sections. To create a helping task, write this:\n\n```js\ngulp.task(\"styleguide:addsection\", function() {\n  return gulp.src('path/to/components/**/*.less')\n    .pipe(styleguide.addSection())\n    .pipe(gulp.dest('path/to/components/'))\n});\n```\n\nUse this task with the parameters:\n\n```sh\ngulp styleguide:new-section --name=NewSection --order=6.2.1\n```\n\n**IMPORTANT**: Check diff after doing this change!\n\n**NOTE**: The tool also makes KSS comment block for a new section if it knows which file it should belong.\n\nThe `addSection` method is parametrized, you may tell which parser to use for the files with certain extension (by analogy to `generate` helper):\n\n```js\n.pipe(styleguide.addSection({\n  parsers: {\n    scss: 'sass'\n  }\n}))\n```\n\n**NOTE**: Be careful with `postcss` parser. It may not preserve new lines and indents.\n\n## Demo\n\nBuild demo style guide and start a server on port 3000\n\n```bash\nnpm run demo\n```\n\nNote: If you installed style guide by cloning repository directly instead of npm you need to run `npm run build` first\n\nThe demo generates style guide to `demo-output` directory.\n\nPoint your browser to \u003chttp://localhost:3000\u003e\n\n## Additional Info\n\n### Articles, blog posts\n\n- [article] [Visual regression tests for SC5 StyleGuide](https://sc5.io/posts/visual-regression-testing/)\n- [article] [Automating Style Guide-Driven Development @ Smashing Magazine](https://www.smashingmagazine.com/2015/03/automating-style-guide-driven-development/)\n- [blog post] [Styleguide the Smaller Things](http://varya.me/en/posts/sc5-styleguide-for-smallers/)\n- [article] [Advanced techniques for the SC5 styleguide generator](https://www.alleyinteractive.com/blog/advanced-techniques-for-the-sc5-styleguide-generator/)\n- [blog post] [Living SC5 Styleguide, the next level](http://varya.me/en/posts/sc5-style-guide-next-level/)\n- [conference talk] [Driving Style Guide-Driven Development](https://youtu.be/gWzYMJjtx-Y)\n\n### Supplementary packages\n\n- [sc5-styleguide-visualtest](https://github.com/SC5/sc5-styleguide-visualtest)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSC5%2Fsc5-styleguide","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FSC5%2Fsc5-styleguide","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSC5%2Fsc5-styleguide/lists"}