silverstripe-styleguide

Generates a styleguide for a SilverStripe theme using CSS documentation.

Requirements

SilverStripe 4 or higher

Installation

$ composer require benmanu/silverstripe-styleguide

Basic Usage

Define the base css/scss folder through the site config.

BenManu\StyleGuide\StyleGuideController:
  paths: 'styleguide/scss'              // the base folder used to render kss.
  css_files:
    - 'themes/default/css/screen.css'   // any css theme files to include in the styleguide.
  js_files:
    - 'themes/default/js/script.js'     // any js theme files to include in the styleguide.

Opens up a controller route /sg.

Comments tagged with Styleguide 1.0, Styleguide 2.0 etc are used to create the main /sg/style-guide navigation. Sub-navigation sections are generated with tags of Styleguide 1.1, Styleguide 1.2 etc. Sub-navigation children are made up of section modifiers like .btn-default, .btn-primary.

Example

You can use the styleguide module scss/css as an example using the below config in your site _config/config.yml file.

BenManu\StyleGuide\StyleGuideController:
  paths: 'styleguide/scss'
  css_files:
    - 'styleguide/dist/css/screen.css'

Kitchen Sink CSS Example

/*
#Components

All the components!

Styleguide 1.0
*/

/*
#Buttons

Use the button classes on an <a>, <button>, or <input> element.

Markup:
<a class="btn $modifierClass">Button</a>

Template: Includes/Button

SectionTemplate: BenManu/StyleGuide/Includes/SGColorPalette

Deprecated:
If there was a deprecation notice it would go here.

Experimental:
If there was any experimental notes they would go here.

.btn-default - Standard button.
.btn-default:hover - Subtle hover highlight.
.btn-primary - Provides extra visual weight and identifies the primary action in a set of buttons.
.btn-success - Indicates a successful or positive action.
.btn-danger - Indicates a dangerous or potentially negative action.

$success - The success hex code variable.
$danger - The danger hex code variable.

Compatible in IE6+, Firefox 2+, Safari 4+.

Styleguide 1.1
*/

See the KSS documentation for further details, with a couple of exceptions being the Template:, and SectionTemplate: parameters. The Template: parameter will render a SilverStripe template file as the example (see Fixtures below), and the SectionTemplate: will render a SilverStripe template file as the Section display.

All comment descriptions are treated as markdown and parsed through parsedown.

Section And SectionTemplate

Fixtures

A yml fixture file can be created in the (project)/styleguide/ directory called fixture.yml, used to populate template variables.

All template files should be placed under the key Template, example:

Template:
  Includes/Footer:
    FooterContent: '<p>Here is some footer content</p>'

Alternatively you can reference other non-template values to populate relationships (has_one, has_many, many_many) and field values, example:

SiteConfig:
  main:
    Title: MySite Title
Site:
  link1:
    Link: #link1
    Text: Link 1
  link2:
    Link: #link2
    Text: Link 2
  link3:
    Link: #link3
    Text: Link 3
StyleGuide:
  main:
    Content: '<p>Here is some footer content</p>'

Template:
  Includes/Footer:
    SiteConfig: =>SiteConfig.main
    FooterLinks: =>Site.link1, =>Site.link2, =>Site.link3
    FooterContent: =>StyleGuide.main.Content

Pages

A yml fixture file can be created in the (project)/styleguide/ directory called pages.yml, used to create additional main and children pages. The Template parameter should be the same name as a SilverStripe template file in your theme.

All template files should be placed under the key Page, example:

Page:
  documentation:
    Title: Documentation
    Template: SGDocumentation
  performanceMonitoring:
    Title: Performance Monitoring
    Template: SGPerformanceMonitoring

Alternatively you can populate a Children parameter referencing a list of child pages to include in the sub-navigation:

Documentation:
  general:
    Title: General
    Template: SG_General
  css:
    Title: Css
    Template: SG_Css
  js:
    Title: Js
    Template: SG_Js
  git:
    Title: Git
    Template: SG_Git
  images:
    Title: Images and icons
    Template: SG_ImagesAndIcons

Children:
  child1:
    Title: Child 1
    Template: SGChild
  child2:
    Title: Child 2
    Template: SGChild

Page:
  documentation:
    Title: Documentation
    Children: =>Documentation.general, =>Documentation.css, =>Documentation.js, =>Documentation.git, =>Documentation.images
  performanceMonitoring:
    Title: Performance Monitoring
    Template: SGPerformanceMonitoring
    Children: =>Children.child1, =>Children.child2

Project Links

• KSS
• parsedown