Issue 8 - Styleguide Integration with Webpack

README.md

@@ -177,3 +177,13 @@ Babel is configured to use [babel-plugin-transform-runtime](https://www.npmjs.co
 ## Contributing
 
 TODO: GENERAL INFO ON CONTRIBUTING TO THIS IF WE HAVE GUIDELINES OR OTHER THINGS
+
+## Styleguide
+
+When compiled, the styleguide by default can be found at `/styleguide`.
+
+KSS Node uses a slight variation of markdown to populate Handlebars
+templates and create your styleguide. This markdown should be included
+in relevant CSS files, and provides inline documentation of your CSS as
+a nice byproduct. Detailed examples can be found in the
+[KSS Node project repo](https://github.com/kss-node/kss-node).

config/project.config.js

@@ -19,6 +19,7 @@ const config = {
   dir_public : 'public',
   dir_server : 'server',
   dir_test   : 'tests',
+  dir_styleguide : 'dist/styleguide',
 
   // ----------------------------------
   // Server Configuration
@@ -116,7 +117,40 @@ config.paths = {
   base   : base,
   client : base.bind(null, config.dir_client),
   public : base.bind(null, config.dir_public),
-  dist   : base.bind(null, config.dir_dist)
+  dist   : base.bind(null, config.dir_dist),
+  styleguideOutput : base.bind(null, config.dir_styleguide)
+};
+
+// ----------------------------------
+// Styleguide Configuration
+// ----------------------------------
+config.styleguide = {
+
+  enabled : true,
+  version : '0.0.1',
+  title   : 'Caxy Front End Starter Kit Style Guide',
+
+  // Source directories for KSS documentation.
+  source: [
+    config.paths.client('styles'),
+    config.paths.client('styleguide/pattern-markup'),
+    config.paths.client('styleguide/project-assets')
+  ],
+
+  builder: config.paths.base('node_modules/kss-caxy-zaba-template'),
+
+  // Custom SASS files to be included in styleguide, but not the project/application.
+  sass: {
+    files: [
+      config.paths.client('styleguide/project-assets/_project-specific.scss')
+    ],
+      includePaths: [
+      config.paths.base('node_modules'),
+      config.paths.client('styles')
+    ]
+  },
+
+  destination: '/styleguide'
 };
 
 // ========================================================

config/styleguide.config.js

@@ -0,0 +1,66 @@
+const project = require('../config/project.config');
+
+/**
+ * Configuration object for the kss-node styleguide.
+ *
+ * This config is passed into StyleguidePlugin (caxy-styleguide-webpack-plugin) in webpack.config.js
+ * when the styleguide is enabled.
+ *
+ *
+ * KSS Custom Options
+ *
+ * All of these are optional, but they provide hooks between KSS and the current
+ * handlebars approach that allow for extra information to be displayed.
+ *
+ * All of these are benign (that is, if you don't use them, nothing happens) aside
+ * from `status`; `status` defaults to 'In Development' and as such needs planning
+ * to accommodate effectively.
+ *
+ * hidemarkup
+ * Not all patterns need to be accompanied by markup. In these cases, enabling this and
+ * adding hidemarkup: true to a given KSS markup section will hide that section's markup.
+ *
+ * patterntype
+ * Displays the atomic design pattern type of the current pattern.
+ *
+ * containspatterns
+ * If the current pattern contains other patterns defined in the styleguide, listing them
+ * here can be helpful (can include links).
+ *
+ * devnotes
+ * In cases where clients need to use the styleguide for use reference and devs need
+ * to reference it for implementation, devnotes can be used to split development-specific
+ * notes into a different area.
+ *
+ * status
+ * For projects that will require ongoing work or continuous integration, it may be useful
+ * to display the status of a given pattern.
+ */
+const styleguideConfig = {
+  // Project-specific settings pulled from project.config.js.
+  styleguide_version: project.styleguide.version,
+  title: project.styleguide.title,
+  destination: project.paths.styleguideOutput(),
+
+  // Source directories for KSS documentation.
+  source: project.styleguide.source,
+
+  // Custom SASS files to be included in styleguide, but not the project/application.
+  sass: project.styleguide.sass,
+
+  builder: project.styleguide.builder,
+
+  // Pattern Status filters will be made available when this is set to false.
+  hide_pattern_status: true,
+
+  // KSS Custom Options
+  custom: [
+    'hidemarkup',
+    'patterntype',
+    'containspatterns',
+    'devnotes',
+    'status'
+  ]
+};
+
+module.exports = styleguideConfig;

config/webpack.config.js

@@ -68,6 +68,14 @@ webpackConfig.plugins = [
   })
 ];
 
+// Add StyleguidePlugin if styleguide is enabled.
+if (project.styleguide.enabled) {
+  const StyleguidePlugin = require('caxy-styleguide-webpack-plugin');
+  const styleguideConfig = require('./styleguide.config');
+
+  webpackConfig.plugins.push(new StyleguidePlugin(styleguideConfig));
+}
+
 // Ensure that the compiler exits on errors during testing so that
 // they do not get skipped and misreported.
 if (__TEST__ && !argv.watch) {

package.json

@@ -74,6 +74,8 @@
   "bugs": "https://github.com/caxy/front-end-starter-kit/issues",
   "homepage": "https://github.com/caxy/front-end-starter-kit#readme",
   "dependencies": {
+    "caxy-styleguide-webpack-plugin": "^0.0.4",
+    "kss-caxy-zaba-template": "^0.0.5",
     "normalize-css": "^2.3.1"
   },
   "devDependencies": {
@@ -100,6 +102,7 @@
     "imports-loader": "^0.7.0",
     "ip": "^1.1.4",
     "json-loader": "^0.5.4",
+    "kss": "^3.0.0-beta.17",
     "node-sass": "^4.3.0",
     "nodemon": "^1.11.0",
     "path": "^0.12.7",

server/main.js

@@ -46,6 +46,9 @@ if (project.env === 'development') {
   // when the application is compiled.
   app.use(express.static(project.paths.public()));
 
+  // Serve the KSS styleguide as static assets.
+  app.use(project.styleguide.destination, express.static(project.paths.styleguideOutput()));
+
   // This rewrites all routes requests to the root /index.html file
   // (ignoring file requests). If you want to implement universal
   // rendering, you'll want to remove this middleware.

src/main.js

@@ -3,10 +3,15 @@ import './styles/core.scss'
 const MOUNT_NODE = document.getElementById('root');
 
 let render = () => {
+  if ((typeof __STYLEGUIDE__ !== 'undefined' && __STYLEGUIDE__)) {
+    // Do not do anything when on the styleguide.
+    return;
+  }
+
   MOUNT_NODE.innerHTML = 'Caxy Front End Starter Kit!';
 };
 
-if (__DEV__) {
+if (__DEV__ && (typeof __STYLEGUIDE__ === 'undefined' || !__STYLEGUIDE__)) {
   if (module.hot) {
     // Development render functions.
     const renderApp = render;

src/styleguide/README.md

@@ -1 +1,72 @@
-Assets used in the styleguide that are not used in the application
+# KSS Styleguide
+
+## Folder Structure
+
+The styleguide needs access to three sets of resources:
+
+* Pattern Markup
+* Project Assets
+* KSS Builder
+
+### Pattern Markup
+
+KSS-node crawls through assets to find any markup referenced in a 
+project's SCSS files. For example:
+
+~~~~
+// Pattern Name
+//
+// Pattern description...
+//
+// Markup: <span class="example-span">Example Span</span>
+//
+// Styleguide 1.2.3
+~~~~
+
+In certain circumstances, this markup can become unwieldy to include in
+this way. When markup becomes longer than a couple of lines, it's best 
+to move it into a separate markup file and reference it like this
+instead:
+
+~~~~
+// Pattern Name
+//
+// Pattern description...
+//
+// Markup: example-span.html
+//
+// Styleguide 1.2.3
+~~~~
+
+KSS allows you to identify certain folders as `source` folders for 
+styleguide documentation. This project has the `pattern-markup` folder
+set as a source by default.
+
+As long as the `example-span.html` referenced above file is found 
+somewhere in one of the `source` folders, the KSS builder will pull it
+in to the compiled styleguide in the appropriate place.
+
+
+### Project Assets
+
+While effort has been taken to separate project assets and code from 
+assets that are solely concerned with styleguide rendering and population,
+there are some minor needs to project assets to be made available to the
+styleguide: *Breakpoint definition* and *Color Swatch definition*. 
+
+There may be other use cases that can be considered as needed, and the
+following question should be used to asses them:
+
+Would this SCSS/CSS ever exist in the project's Production state?
+
+If the answer is "no," then the SCSS/CSS belongs in this folder.
+
+Use caution, however- the entire point of a living styleguide is to have
+an accurate representation of the final production code. To add in
+overrides or special-case considerations flies in the face of that goal.
+
+
+### KSS Builder
+
+Any KSS Node build can be used, but some kind of template is needed for
+KSS to populate and create the final styleguide files with.

src/styleguide/pattern-markup/swatches_example.html

@@ -0,0 +1,17 @@
+<div class="kss-style">
+
+  <h3 class="kss-title">Example Color Set 1</h3>
+  <ul class="has-swatches kss-style">
+    <li class="kss-swatch example-1--light"><span class="dot"></span></li>
+    <li class="kss-swatch example-1--base"><span class="dot"></span></li>
+    <li class="kss-swatch example-1--dark"><span class="dot"></span></li>
+  </ul>
+
+  <h3 class="kss-title">Example Color Set 2</h3>
+  <ul class="has-swatches kss-style">
+    <li class="kss-swatch example-2--light"><span class="dot"></span></li>
+    <li class="kss-swatch example-2--base"><span class="dot"></span></li>
+    <li class="kss-swatch example-2--dark"><span class="dot"></span></li>
+  </ul>
+
+</div>

src/styleguide/pattern-markup/titles.html

@@ -0,0 +1,6 @@
+<h1>Title 1: Lorem ipsum dolor sit amet, consectetur adipisicing elit. Facere tempora est, repellendus voluptate libero laboriosam incidunt ratione.</h1>
+<h2>Title 2: Lorem ipsum dolor sit amet, consectetur adipisicing elit. Iure nemo deserunt consequuntur expedita officiis, vero, quia unde odit voluptas.</h2>
+<h3>Title 3: Lorem ipsum dolor sit amet, consectetur adipisicing elit. Ipsam nulla exercitationem ut voluptatem deserunt laborum dicta assumenda placeat, eos dolorum.</h3>
+<h4>Title 4: Lorem ipsum dolor sit amet, consectetur adipisicing elit. Quam voluptate fuga nihil saepe, unde, possimus tempore aut libero animi iusto est excepturi!</h4>
+<h5>Title 5: Lorem ipsum dolor sit amet, consectetur adipisicing elit. Quo architecto sunt asperiores veniam molestias debitis quasi. Temporibus labore natus ab harum maiores.</h5>
+<h6>Title 6: Lorem ipsum dolor sit amet, consectetur adipisicing elit. Nam enim totam quod illo, non, sed architecto illum est cupiditate, facere, eos.</h6>

src/styleguide/pattern-markup/typography.html

@@ -0,0 +1,37 @@
+
+<h1>Heading Level 1</h1>
+
+<p class="copy--lead-in">Lorem ipsum dolor sit amet, consectetur adipisicing elit. Dolorem beatae mollitia itaque expedita necessitatibus ratione adipisci, iure repellat porro quas consectetur non eveniet voluptas id fuga aperiam sequi. Debitis, nihil!</p>
+
+<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. <a href="#">Donec non enim</a> in turpis pulvinar facilisis. Donec eu libero sit amet quam egestas semper. <em>Aenean ultricies mi vitae est.</em> Mauris placerat eleifend leo. Quisque sit amet est et sapien ullamcorper pharetra. Vestibulum erat wisi, <strong>condimentum sed</strong>, ornare sit amet, wisi. Aenean fermentum, elit eget tincidunt condimentum, eros ipsum rutrum orci, sagittis tempus lacus enim ac dui. Ut felis.</p>
+
+<p>Morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo. Quisque sit amet est et sapien ullamcorper pharetra. Vestibulum erat wisi, condimentum sed, commodo vitae, ornare sit amet, wisi. Aenean fermentum, elit eget tincidunt condimentum, eros ipsum rutrum orci, sagittis tempus lacus enim ac dui. Donec non enim in turpis pulvinar facilisis. Ut felis. Praesent dapibus, neque id cursus faucibus, tortor neque egestas augue, eu vulputate magna eros eu erat. Aliquam erat volutpat. Nam dui mi, tincidunt quis, accumsan porttitor, facilisis luctus, metus</p>
+
+<h2>Heading Level 2</h2>
+
+<ol>
+   <li>Lorem ipsum dolor sit amet, consectetuer adipiscing elit.</li>
+   <li>Aliquam tincidunt mauris eu risus.</li>
+</ol>
+
+<h3>Heading Level 3</h3>
+
+<p>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Ducimus dolore excepturi ad expedita, doloremque id enim iusto ratione tempore amet perferendis numquam, nulla nostrum magnam quam neque, necessitatibus dicta! Ipsa!</p>
+
+<blockquote>
+	"Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus magna. Cras in mi at felis aliquet congue. Ut a est eget ligula molestie gravida. Curabitur massa. Donec eleifend, libero at sagittis mollis, tellus est malesuada tellus, at luctus turpis elit sit amet quam. Vivamus pretium ornare est."
+	<footer>
+	— <cite>Source Person, Additional Info</cite>
+	</footer>
+</blockquote>
+
+<p>Consectetur adipisicing elit. Qui unde voluptates voluptatem et autem eos eaque iusto atque ea aliquam laborum cupiditate pariatur explicabo, dicta molestias sapiente laboriosam eveniet! Rem.</p>
+
+<h4>Heading Level 4:</h4>
+
+<ul>
+   <li>Lorem ipsum dolor sit amet, consectetuer adipiscing elit.</li>
+   <li>Aliquam tincidunt mauris eu risus.</li>
+</ul>
+
+<p>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Ducimus dolore excepturi ad expedita, doloremque id enim iusto ratione tempore amet perferendis numquam, nulla nostrum magnam quam neque, necessitatibus dicta! Ipsa!</p>