From 0196e09412daa6df641a1c5358b1e318cce55f3b Mon Sep 17 00:00:00 2001 From: Ryan Domingue Date: Tue, 12 Dec 2017 14:52:23 -0800 Subject: [PATCH 1/3] Updates links throughout --- README.md | 54 +++++++++++++++++++++++++------------ dist/README.md | 5 +++- src/cli/README.md | 6 +++-- src/defaultConfig/README.md | 14 +++++++--- src/web/README.md | 5 +++- templates/README.md | 14 +++++++--- 6 files changed, 71 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index ecb325c..0d79592 100644 --- a/README.md +++ b/README.md @@ -1,34 +1,34 @@ # Huron: A Prototype Build System -Huron is a one-stop shop for generating both in-browser style guides and in-browser prototypes. Huron integrates with [Webpack](https://webpack.github.io/) to provide a CLI that processes Knyle Style Sheets [(KSS)](http://warpspire.com/kss/) documentation into style guides and prototypes. Huron's use of Webpack's Hot Module Reloading [HMR](https://webpack.github.io/docs/hot-module-replacement.html) system provides a quick and seamless development experience. +Huron is a one-stop shop for generating both in-browser style guides and in-browser prototypes. Huron integrates with [Webpack][webpack_home] to provide a CLI that processes Knyle Style Sheets [(KSS)][kss_home] documentation into style guides and prototypes. Huron's use of Webpack's Hot Module Reloading [HMR][webpack_hmr] system provides a quick and seamless development experience. ## Get started example -For a bare-bones demo, [see this example repository](https://github.com/alleyinteractive/huron-examples). +For a bare-bones demo, [see this example repository][huron_examples]. ## Installation -Huron can be installed via [NPM](https://www.npmjs.com/package/huron). +Huron can be installed via [NPM][npm_huron]. ``` npm install huron --save ``` -Once installed, you'll need to write a configuration. The default settings and how to modify them is documented in the [configuration](src/default-config/README.md) documentation. +Once installed, you'll need to write a configuration. The default settings and how to modify them is documented in the [configuration][configuration_docs] documentation. Then, start the CLI with the respective paths to your configs: ``` npm run huron -w webpack.config.js -c huron.config.js ``` -Once the CLI has started, you can access your prototype(s) at `localhost:8080/dist/[prototype-name].html`, in which port 8080 and `dist` are the default settings for `port` and `root` respectively. You can find the defaults for all huron options and how to change them in the [configuration](src/default-config/README.md) documentation. +Once the CLI has started, you can access your prototype(s) at `localhost:8080/dist/[prototype-name].html`, in which port 8080 and `dist` are the default settings for `port` and `root` respectively. You can find the defaults for all huron options and how to change them in the [configuration][configuration_docs] documentation. To build your prototype files for production, run ``` npm run huron-build -w webpack.config.js -c huron.config.js ``` -The files will be accessible through whatever folder you specified as your huron root in the [configuration](src/default-config/README.md) file. +The files will be accessible through whatever folder you specified as your huron root in the [configuration][configuration_docs] file. ## Writing KSS, templates and data -KSS is a documentation syntax and styleguide generator. All documentation should be located in your stylesheets, and should largely follow the regular [KSS syntax](http://warpspire.com/kss/syntax/). However, Huron uses [kss-node](https://github.com/kss-node/kss-node) which includes some changes, and there are a few differences specific to Huron as well. All your KSS should include the following: +KSS is a documentation syntax and styleguide generator. All documentation should be located in your stylesheets, and should largely follow the regular [KSS syntax][kss_syntax]. However, Huron uses [kss-node][kss_node] which includes some changes, and there are a few differences specific to Huron as well. All your KSS should include the following: * **Title** - This is the first line of your KSS comment block * **Description** - This starts on the second line of your KSS comment block (may be multiple lines), and will be exported to a separate file by Huron after running through a markdown compiler. As is probably obvious, this means you may use markdown your KSS descriptions * **Modifiers** - These are different variations of your component. Modifiers are used _exclusively_ in the Huron styleguide helper tags, and are not required to render a variant of a template in your prototypes (we'll get into that later). So for example, you could include a 'with-images' variant of your component markup, but not include it in the KSS modifiers block. This would allow you to still use that variant in your prototypes, but would not show up in the styleguide. @@ -65,7 +65,7 @@ KSS is a documentation syntax and styleguide generator. All documentation should * _NOTE: As of now, Huron only supports one KSS documentation block per file, meaning it's heavily geared toward CSS preprocessors like SASS or LESS. This is an issue on our radar, however, and will be implemented at some point._ ## Writing prototypes -In Huron, everything is a "prototype" (even a style guide). Unlike previous versions, you now only have to write the prototype _content_ instead of wrangling all the surrounding HTML document boilerplate as well. This is accomplished via the [HTML webpack plugin](https://github.com/ampedandwired/html-webpack-plugin). Configuration of each prototype is discussed in the [config readme](src/default-config/README.md). All you need to know for now is your prototype files should be located in a `prototypes` directory within your SASS/CSS source directory, and should be named in the format `prototype-[prototype name].html`. +In Huron, everything is a "prototype" (even a style guide). Unlike previous versions, you now only have to write the prototype _content_ instead of wrangling all the surrounding HTML document boilerplate as well. This is accomplished via the [HTML webpack plugin][html_webpack_plugin]. Configuration of each prototype is discussed in the [config readme][configuration_docs]. All you need to know for now is your prototype files should be located in a `prototypes` directory within your SASS/CSS source directory, and should be named in the format `prototype-[prototype name].html`. * You may include any valid HTML markup in your prototype. * Huron uses its own custom syntax for inserting templates from your KSS. This is accomplished via three data attributes: * `[data-huron-id]` - The KSS styleguide section reference URI containing the template you want. As described above, to get the reference URI you simply convert any `.` to `-` in the section reference you wrote in the KSS. For example, the section `header.navigation` would be inserted using a `huron-id` of `header-navigation`. @@ -73,21 +73,41 @@ In Huron, everything is a "prototype" (even a style guide). Unlike previous vers * `template` - This is the type you'll use most frequently, and will insert anything in your KSS `markup` field. * `description` - Type to insert the KSS description field * `prototype` - This is mostly used by the HTML webpack plugin to insert your prototype content, but you can use it as well if necessary. - * `section` - Insert the entire KSS section using the `templates/section.hbs` template. More on this template is located in the [templates readme](templates/README.md). + * `section` - Insert the entire KSS section using the `templates/section.hbs` template. More on this template is located in the [templates readme][template_docs]. * `[data-huron-modifier]` - Used to specify a particular top-level data field with which to render your markup. Using the example data above, you could use `data-huron-modifier="type-two"` to use the data fields within the `type-two` property to render and insert your KSS markup. * You may attach the Huron data attributes to any tag, but generally we use a generic `
` - * A separate HTML document is automatically built for each of your configured prototypes using the HTML webpack plugin and a custom EJS [template](templates/prototype-template.ejs). More information on this can be found in the [templates readme](templates/README.md). + * A separate HTML document is automatically built for each of your configured prototypes using the HTML webpack plugin and a custom [Handlebars template][hbs_template]. More information on this can be found in the [templates readme][template_docs]. ## Using CSS Modules -If you're using CSS modules in your production site, it makes sense to also use it when developing in-browser prototypes. Huron supports usage of certain CSS modules implementations (specifically any that is capable of producing JSON output containing localized classes). All that's needed in order to configure this is the `classNames` configuration property, more details for which are in the [configuration docs](src/default-config/README.md). Once you have that set up, all classes will be be provided to every template. These classes are available on a `classNames` object, under which all classes are nested and organized by filename. For example, if your build produces two JSON files for localized classes called `article.json` and `home.json`, you can access those classes in your huron templates via `classNames.article[className]` and `classNames.home[className]` respectively. +If you're using CSS modules in your production site, it makes sense to also use it when developing in-browser prototypes. Huron supports usage of certain CSS modules implementations (specifically any that is capable of producing JSON output containing localized classes). All that's needed in order to configure this is the `classNames` configuration property, more details for which are in the [configuration docs][configuration_docs]. Once you have that set up, all classes will be be provided to every template. These classes are available on a `classNames` object, under which all classes are nested and organized by filename. For example, if your build produces two JSON files for localized classes called `article.json` and `home.json`, you can access those classes in your huron templates via `classNames.article[className]` and `classNames.home[className]` respectively. -A sample of how to set this up can be found in the [`huron-examples` repo](https://github.com/alleyinteractive/huron-examples) +A sample of how to set this up can be found in the [`huron-examples` repo][huron_examples] ## For more specific information This file contains basic information on Huron installation and writing prototypes. However, there are several other subsections of this documentation: -* [Configuration](src/default-config/README.md) - Configuration for Huron and for your local webpack setup -* [Templates](templates/README.md) - Peripheral template documentation -* [CLI](src/cli/README.md) - General information on the Huron CLI. Source code is further documented via jsdoc -* [Web](src/web/README.md) - General information on browser script for inserting/replacing markup. Source code is further documented via jsdoc -* [Dist](dist/README.md) - General information on the distribution (build) directory. +* [Configuration][configuration_docs] - Configuration for Huron and for your local webpack setup +* [Templates][template_docs] - Peripheral template documentation +* [CLI][cli_docs] - General information on the Huron CLI. Source code is further documented via jsdoc +* [Web][web_docs] - General information on browser script for inserting/replacing markup. Source code is further documented via jsdoc +* [Dist][dist_docs] - General information on the distribution (build) directory. + + +[webpack_home]: https://webpack.js.org/ +[webpack_hmr]: https://webpack.js.org/concepts/hot-module-replacement/ +[kss_home]: http://warpspire.com/kss/ +[kss_syntax]: http://warpspire.com/kss/syntax/ +[kss_node]: https://github.com/kss-node/kss-node +[html_webpack_plugin]: https://github.com/ampedandwired/html-webpack-plugin + + +[npm_huron]: https://www.npmjs.com/package/huron +[huron_examples]: https://github.com/alleyinteractive/huron-examples/ + + +[configuration_docs]: src/defaultConfig/README.md +[template_docs]: templates/README.md +[hbs_template]: templates/prototypeTemplate.hbs +[cli_docs]: src/cli/README.md +[web_docs]: src/web/README.md +[dist_docs]: dist/README.md diff --git a/dist/README.md b/dist/README.md index 23d01e7..26a57ec 100644 --- a/dist/README.md +++ b/dist/README.md @@ -1,3 +1,6 @@ # Distribution directory -This directory contains the Huron source code that will be distributed via NPM. If you are developing for Huron, you must run the `npm run build` script before pushing and/or merging your changes. This script will run the source code through `eslint`, using the [airbnb standards](https://github.com/airbnb/javascript), and `babel`. \ No newline at end of file +This directory contains the Huron source code that will be distributed via NPM. If you are developing for Huron, you must run the `npm run build` script before pushing and/or merging your changes. This script will run the source code through `eslint`, using the [airbnb standards][airbnb_standards], and `babel`. + + +[airbnb_standards]: https://github.com/airbnb/javascript diff --git a/src/cli/README.md b/src/cli/README.md index c5422fa..96e4600 100644 --- a/src/cli/README.md +++ b/src/cli/README.md @@ -2,9 +2,11 @@ Huron's CLI is extremely simple and only requires two flags. * `--config` a flag to point Huron to your webpack config, which also contains a configuration for Huron itself -* `--production` a flag to tell Huron whether or not you're building for production. By default (without this flag set), Huron will build and server your assets via HMR and [webpack-dev-server](https://webpack.github.io/docs/webpack-dev-server.html). +* `--production` a flag to tell Huron whether or not you're building for production. By default (without this flag set), Huron will build and server your assets via HMR and [webpack-dev-server][webpack_dev_server]. * You may also run `huron help` to see documentation on each CLI flag Example build command: `node huron/dist/cli/huron-cli.js --config 'client/config/webpack.config.js' --production`. -The source code for this CLI is documented via jsdoc. Run `npm install` inside the Huron directory and then run `npm run doc`. Documentation index page will be located at `source-docs/index.html`. \ No newline at end of file +The source code for this CLI is documented via jsdoc. Run `npm install` inside the Huron directory and then run `npm run doc`. Documentation index page will be located at `source-docs/index.html`. + +[webpack_dev_server]: https://webpack.js.org/guides/development/#using-webpack-dev-server diff --git a/src/defaultConfig/README.md b/src/defaultConfig/README.md index 25693be..b1fe9ae 100644 --- a/src/defaultConfig/README.md +++ b/src/defaultConfig/README.md @@ -24,7 +24,7 @@ Object containing options to pass through to KSS-node. I can't find a good sourc * **output** {string} : default `'partials'` - Relative path (relative to the `huron.root` option) to the directory where you want your templates to be generated. * **port** {number} : default `8080` - `localhost` port from which to server your prototypes via webpack-dev-server -* **prototypes** {array} : default `['index']` - Array of prototypes to generate via HTML webpack plugin. For each array entry you can either pass in a single string corresponding to the title of the prototype, or an object containing option overrides for HTML webpack plugin [(configuration)](https://github.com/ampedandwired/html-webpack-plugin). If you use an object, you must at least provide a `title` field. The title field, whether passed in as a string or the `title` property value, must be the same name as your prototype file located in your `prototypes` directory. So for example, if you provided `['homepage']` in the prototypes option, you would need to have a `prototypes/prototype-homepage.html` file in order for the prototype to display correctly. +* **prototypes** {array} : default `['index']` - Array of prototypes to generate via HTML webpack plugin. For each array entry you can either pass in a single string corresponding to the title of the prototype, or an object containing option overrides for HTML webpack plugin [(configuration)][html_webpack_plugin]. If you use an object, you must at least provide a `title` field. The title field, whether passed in as a string or the `title` property value, must be the same name as your prototype file located in your `prototypes` directory. So for example, if you provided `['homepage']` in the prototypes option, you would need to have a `prototypes/prototype-homepage.html` file in order for the prototype to display correctly. * **root** {string} : default `'dist/'` - Root directory for `webpack-dev-server`. All static assets you need for your prototype(s) should be located in this directory. The `output` option should be relative to this path. * **sectionTemplate** {string} : default `path.join(__dirname, '../templates/section.hbs')` - Override for the template used to produce styleguide sections. This should always be a handlebars file, and will utilize the KSS data as its source. * **classNames** {string} : For use with CSS Modules. This option should point to a directory with JSON files containing localized classnames. NOTE: at the moment this will only work a CSS Modules implementation that produces JSON output, like `postcss-modules`. The CSS modules implementation offered by the `modules` option in `css-loader` currently will not work. @@ -40,7 +40,7 @@ Object containing options to pass through to KSS-node. I can't find a good sourc } ``` -Object containing a webpack loader for your template files and a corresponding file extension. Instructions for configuring a webpack loader can be found [here](https://webpack.github.io/docs/configuration.html#module-loaders). +Object containing a webpack loader for your template files and a corresponding file extension. Instructions for configuring a webpack loader can be found [here][module_loaders]. * **window** {object} : default `{}` - Object containing variables that should be attached to the global `window` object on every prototype. * Complete default huron configuration object: @@ -76,7 +76,7 @@ huron: { Huron will attempt to merge its own configuration requirements for webpack with your local configuration, allowing you to use the same build tools (and resulting scripts and styles) in your prototypes as you do on your live site. * Huron will automatically add `webpack-dev-server/client?http://localhost:${huron.port}`, `webpack/hot/dev-server` and the Huron front-end script to your configured entry point, so you do not need to worry about configuring this. In addition, Huron will de-dupe the `HotModuleReplacementPlugin()` if you're using it in your production webpack configuration. * Huron will automatically add configurations for the `html-loader` and `json-loader` for HTML templates and JSON data respectively -* The HTML webpack plugin will be largely configured automatically, so you're only required to supply the title of the prototype. As described above, however, you may reconfigure the options. Just beware that this may break your setup, especially if you override the `chunks` option. NOTE: this is also the method by which you may supply a custom EJS template for your prototypes. Again, do this at your own risk and consult the [default template](../templates/prototype-teplate.ejs) first. +* The HTML webpack plugin will be largely configured automatically, so you're only required to supply the title of the prototype. As described above, however, you may reconfigure the options. Just beware that this may break your setup, especially if you override the `chunks` option. NOTE: this is also the method by which you may supply a custom Handlebars template for your prototypes. Again, do this at your own risk and consult the [default template][prototype_template] first. * Huron will override the `devServer` property in your webpack config in favor of its own. This includes the `devServer.stats` object. * As described above, your Huron entry point should use the following guidelines: * Huron will only support a _single_ entry point. This entry point may be an array of modules, however. @@ -84,3 +84,11 @@ Huron will attempt to merge its own configuration requirements for webpack with * If you're using `extract-text-webpack-plugin` you will need to conditionally disable this for Huron in order to hot reload your styles. * In addition, your styles should conditionally run through the `style-loader` to properly support HMR. * To support the above conditions, our recommendation is to set a variable in your webpack config based on the npm lifecycle event. Example: `const isHuron = 'huron' === process.env.npm_lifecycle_event;`. This would be set to `true` when you run `npm run huron`. + + +[html_webpack_plugin]: https://github.com/ampedandwired/html-webpack-plugin +[module_loaders]: https://webpack.github.io/docs/configuration.html#module-loaders + + +[configuration_docs]: src/defaultConfig/README.md +[prototype_template]: ../../templates/prototypeTemplate.hbs diff --git a/src/web/README.md b/src/web/README.md index 19c3776..826c651 100644 --- a/src/web/README.md +++ b/src/web/README.md @@ -5,4 +5,7 @@ This directory contains the source code for the Huron browser script, used to in * Template data (JSON) * KSS source (CSS). NOTE: Some KSS fields may cause problems with HMR, most notably the styleguide section reference. This part of Huron is actively under refinement. Changes to the KSS `description`, `header`/`title` or in-line markup should work just fine, however. -Further documentation on the InsertNodes class, which contains all this logic, is provided via jsdoc. See the [CLI](src/cli/README.md) readme \ No newline at end of file +Further documentation on the InsertNodes class, which contains all this logic, is provided via jsdoc. See the [CLI][cli_docs] README. + + +[cli_docs]: ../cli/README.md diff --git a/templates/README.md b/templates/README.md index b3e06e0..1040046 100644 --- a/templates/README.md +++ b/templates/README.md @@ -1,8 +1,16 @@ # Default Templates -This directory contains default layout templates for styleguide [sections](./sections.hbs) and [prototype documents](./prototype-template.ejs). You may override each of these with your own markup. Before you do so, however, it's advised you take a look at the existing templates first. +This directory contains default layout templates for styleguide [section][section] and [prototype][prototype_template] documents. You may override each of these with your own markup. Before you do so, however, it's advised you take a look at the existing templates first. * Styleguide section template: add a path to your own Handlebars template using the Huron `sectionTemplate` configuration field. * Prototype document template: in your Huron `prototypes` configuration array, supply a configuration object for one or more of your prototypes and include a `template` field in that object. This will override the `template` field of the HTML webpack plugin and allow you to supply a custom template. By default, HTML webpack plugin uses EJS for templates. However, for Huron you may also supply a template in the same language as your prototype partials. - * [EJS syntax](http://www.embeddedjs.com/) - * [HTML webpack plugin documentation](https://github.com/ampedandwired/html-webpack-plugin) \ No newline at end of file + * [Handlebars][Handlebars] + * [HTML webpack plugin documentation][html_webpack_plugin] + + +[Handlebars]: http://handlebarsjs.com/ +[html_webpack_plugin]: https://github.com/ampedandwired/html-webpack-plugin + + +[section]: section.hbs +[prototype_template]: prototypeTemplate.hbs From 0dfae7dd654e442bef46f6f8986302b5aa381744 Mon Sep 17 00:00:00 2001 From: Ryan Domingue Date: Tue, 12 Dec 2017 15:17:37 -0800 Subject: [PATCH 2/3] Formatting update for consistency --- src/cli/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/cli/README.md b/src/cli/README.md index 96e4600..732d520 100644 --- a/src/cli/README.md +++ b/src/cli/README.md @@ -9,4 +9,5 @@ Example build command: `node huron/dist/cli/huron-cli.js --config 'client/config The source code for this CLI is documented via jsdoc. Run `npm install` inside the Huron directory and then run `npm run doc`. Documentation index page will be located at `source-docs/index.html`. + [webpack_dev_server]: https://webpack.js.org/guides/development/#using-webpack-dev-server From 22306d6f5543af1298fc49b689a5f4139676bc14 Mon Sep 17 00:00:00 2001 From: Ryan Domingue Date: Wed, 13 Dec 2017 08:54:06 -0800 Subject: [PATCH 3/3] Removes dist/ && rebuild --- dist/README.md | 6 --- dist/huron-assets/prototype-template.ejs | 50 ------------------------ dist/index.js | 3 -- package-lock.json | 4 +- 4 files changed, 2 insertions(+), 61 deletions(-) delete mode 100644 dist/README.md delete mode 100644 dist/huron-assets/prototype-template.ejs delete mode 100755 dist/index.js diff --git a/dist/README.md b/dist/README.md deleted file mode 100644 index 26a57ec..0000000 --- a/dist/README.md +++ /dev/null @@ -1,6 +0,0 @@ -# Distribution directory - -This directory contains the Huron source code that will be distributed via NPM. If you are developing for Huron, you must run the `npm run build` script before pushing and/or merging your changes. This script will run the source code through `eslint`, using the [airbnb standards][airbnb_standards], and `babel`. - - -[airbnb_standards]: https://github.com/airbnb/javascript diff --git a/dist/huron-assets/prototype-template.ejs b/dist/huron-assets/prototype-template.ejs deleted file mode 100644 index 218dc1f..0000000 --- a/dist/huron-assets/prototype-template.ejs +++ /dev/null @@ -1,50 +0,0 @@ - - manifest="<%= htmlWebpackPlugin.files.manifest %>"<% } %>> - - - <%= htmlWebpackPlugin.options.title || 'Huron' %> prototype - <% if (htmlWebpackPlugin.files.favicon) { %> - - <% } %> - <% for (var script in htmlWebpackPlugin.options.js) { %> - - <% } %> - <% for (var stylesheet in htmlWebpackPlugin.options.css) { %> - - <% } %> - - <% for (var css in htmlWebpackPlugin.files.css) { %> - - <% } %> - <% if (htmlWebpackPlugin.options.window) { %> - - <% } %> - - -<% if (htmlWebpackPlugin.options.unsupportedBrowser) { %> - -
- Sorry, your browser is not supported. Please upgrade to - the latest version or switch your browser to use this site. - See outdatedbrowser.com - for options. -
-<% } %> -<% if (htmlWebpackPlugin.options.appMountId) { %> -
-<% } %> -<% if (htmlWebpackPlugin.options.appMountIds && htmlWebpackPlugin.options.appMountIds.length > 0) { %> - <% for (var index in htmlWebpackPlugin.options.appMountIds) { %> -
- <% } %> -<% } %> -
-<% for (var chunk in htmlWebpackPlugin.files.chunks) { %> - -<% } %> - - \ No newline at end of file diff --git a/dist/index.js b/dist/index.js deleted file mode 100755 index 734f03b..0000000 --- a/dist/index.js +++ /dev/null @@ -1,3 +0,0 @@ -#!/usr/bin/env node - -require('./cli'); diff --git a/package-lock.json b/package-lock.json index 01bbcef..cbe5228 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,6 +1,6 @@ { "name": "huron", - "version": "2.3.0-beta.6", + "version": "2.3.1", "lockfileVersion": 1, "requires": true, "dependencies": { @@ -7532,7 +7532,7 @@ "randombytes": { "version": "2.0.5", "resolved": "https://registry.npmjs.org/randombytes/-/randombytes-2.0.5.tgz", - "integrity": "sha512-8T7Zn1AhMsQ/HI1SjcCfT/t4ii3eAqco3yOcSzS4mozsOz69lHLsoMXmF9nZgnFanYscnSlUSgs8uZyKzpE6kg==", + "integrity": "sha1-3ACaJGuNCaF3tLegrne8Vw9LG3k=", "requires": { "safe-buffer": "5.1.1" }