You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+6-3Lines changed: 6 additions & 3 deletions
Original file line number
Diff line number
Diff line change
@@ -4,6 +4,9 @@ If you'd like to contribute to patternlab - node, please do so! There is always
4
4
No pull request is too small.
5
5
6
6
##Guidelines
7
-
1. Please keep your pull requests concise
8
-
2._ALWAYS_ submit it against the [dev branch](https://github.com/pattern-lab/patternlab-node/tree/dev). If this does not occur, I will first, try to redirect you gently, second, port over your contribution manually if time allows, and/or third, close your pull request.
9
-
3. If you can, add some unit tests using the existing patterns
7
+
1. Please keep your pull requests concise and limited to **ONE** substantive change at a time.
8
+
2._ALWAYS_ submit pull requests against the [dev branch](https://github.com/pattern-lab/patternlab-node/tree/dev). If this does not occur, I will first, try to redirect you gently, second, port over your contribution manually if time allows, and/or third, close your pull request.
9
+
3. If you can, add some unit tests using the existing patterns
10
+
11
+
##Coding style
12
+
Regarding code style like indentation and whitespace, follow the conventions you see used in the source already. Add enough source code comments to help the next person.
Copy file name to clipboardExpand all lines: README.md
+67-46Lines changed: 67 additions & 46 deletions
Original file line number
Diff line number
Diff line change
@@ -2,21 +2,59 @@
2
2
3
3
## About the Node Version of Pattern Lab
4
4
5
-
The Node version of Pattern Lab is, at its core, a static site generator. It combines platform-agnostic assets, like the [Mustache](http://mustache.github.io/)-based patterns and the JavaScript-based viewer, with a Node-based "builder" that transforms and dynamically builds the Pattern Lab site. By making it a static site generator, the Node version of Pattern Lab strongly separates patterns, data, and presentation from build logic. The Node version is a work in progress, the [PHP version](https://github.com/pattern-lab/patternlab-php) should be seen as a reference for other developers to improve upon as they build their own Pattern Lab Builders in their language of choice.
5
+
The Node version of [Pattern Lab](http://patternlab.io/) is, at its core, a static site generator. It combines platform-agnostic assets, like the Mustache-based patterns, the JavaScript-based viewer, and the self-contained webserver, with a Node-based "builder" that transforms and dynamically builds the Pattern Lab site.
6
6
7
-
### Getting Started
7
+
This repository contains the vanilla builder logic, grunt and gulp configurations, and some sample template/css/data to illustrate the power and flexibility of the tool.
8
8
9
-
To run patternlab-node, run the following from the command line at the root of whichever directory you want to initialize your project in:
9
+
### Download
10
10
11
-
1.`npm install`
12
-
2.`npm install -g grunt-cli`
13
-
3.`grunt`
11
+
* Download the [latest release of patternlab-node](https://github.com/pattern-lab/patternlab-node/releases/latest) from Github
12
+
* Via npm, run `npm install patternlab-node` (Note this will auto install the grunt version currently. see below)
14
13
15
-
This creates all patterns, the styleguide, and the pattern lab site.
14
+
### Choose Your Adventure! Now Vanilla, Grunt & Gulp
15
+
16
+
This repository ships with two `package.json` files, a `Gruntfile.js`, and a `gulpfile.js`. The default is grunt currently. The core builder is not dependent on either.
17
+
18
+
**HELP WANTED** Please help me test both of the configurations by [reporting](https://github.com/pattern-lab/patternlab-node/blob/dev/CONTRIBUTING.md) any issues encountered.
19
+
20
+
### Getting Started - Grunt
21
+
22
+
To run patternlab-node using grunt, do the following in the directory you downloaded and extracted the zipped release:
23
+
24
+
1. Run `npm install` from the command line
25
+
2. Optionally, delete `package.gulp.json`, `gulpfile.js`, and `builder/patternlab_gulp.js` files if you are certain you don't need it.
26
+
* Not deleting `builder/patternlab_gulp.js` may cause a harmless error when running grunt. Delete it.
27
+
3. Run `grunt` or `grunt serve` from the command line
28
+
29
+
This creates all patterns, the styleguide, and the pattern lab site. It's strongly recommended to run `grunt serve` to see have BrowserSync spin up and serve the files to you.
30
+
31
+
### Getting Started - Gulp
32
+
33
+
To run patternlab-node using gulp, you need to swap out the default grunt configuration. Do the following in the directory you downloaded and extracted the zipped release:
34
+
35
+
1. Rename `package.json` to `package.grunt.json` or delete it if you don't intend on going back
36
+
2. Rename `package.gulp.json` to `package.json`
37
+
3. Run `npm install` from the command line
38
+
4. Run `gulp` or `gulp serve` from the command line
39
+
40
+
This creates all patterns, the styleguide, and the pattern lab site. It's strongly recommended to run `grunt serve` to see have BrowserSync spin up and serve the files to you.
41
+
42
+
### There and Back Again, or Switching Between Grunt and Gulp
43
+
44
+
It's not expected to toggle between the two build systems, but for those migrating between the two configs, here's some general guidelines:
45
+
46
+
* Make sure your `package.json` files are correct per the Getting Started sections.
47
+
* Run `npm cache clear` before installation
48
+
* Delete the contents of `./node_modules` if you want a cleaner installation.
49
+
* Regarding speed, Gulp is faster. BrowserSync takes a bit longer than the old static server to spin up, but its capabilities far outweigh the startup cost.
50
+
51
+
### Upgrading
52
+
53
+
You can find some simple upgrade documenation in it's current home here (unreleased but confirmed to work): [https://github.com/pattern-lab/website/blob/dev/patternlabsite/docs/node/upgrading.md](https://github.com/pattern-lab/website/blob/dev/patternlabsite/docs/node/upgrading.md)
16
54
17
55
### Command Line Interface
18
56
19
-
The following are grunt task arguments you may execute:
57
+
The following are grunt/gulp task arguments you may execute:
20
58
21
59
##### `patternlab`
22
60
With no arguments, patternlab runs the full builder, compiling patterns, and constructing the front-end site.
@@ -30,15 +68,20 @@ Retrieve the version of patternlab-node you have installed
30
68
##### `patternlab:help`
31
69
Get more information about patternlab-node, pattern lab in general, and where to report issues.
32
70
33
-
### Config Options
71
+
### Further Configuration
34
72
35
73
##### Watching Changes
36
-
To have patternlab-node watch for changes to either a mustache template, data, or stylesheets, run `grunt watch`. The `Gruntfile` governs what is watched. It should be easy to add scss or whatever preprocessor you fancy.
74
+
To have patternlab-node watch for changes to either a mustache template, data, or stylesheets, run `grunt|gulp watch` or `grunt|gulp serve`. The `Gruntfile|Gulpfile` governs what is watched. It should be easy to add scss or whatever preprocessor you fancy.
75
+
76
+
##### Preprocessor Support
77
+
The patternlab-node release package ships with some `.scss` files utilized in the creation of the style guide and sample templates, but these are not required. The compilation tasks are commented out in the `Gruntfiles|Gulpfiles` but can be uncommented or changed to meet your needs. Sass modules are not included in `package.json` files - the prevailing thought being if you are familiar enough with preprocessors, you can use the instructions for [grunt-contrib-sass](https://github.com/gruntjs/grunt-contrib-sass) / [gulp-sass](https://github.com/dlmanning/gulp-sass) / _preprocessor of choice_ to install them. Uncomment the preprocessor configuration to fully utilize the example templates, css and style guide.
78
+
79
+
**NOTE:** You may run into issues installing gulp-sass if you don't have the latest Visual Studio on Windows. See [here](https://github.com/sass/node-sass/issues/469) for more information and [this query](https://github.com/sass/node-sass/issues?utf8=%E2%9C%93&q=is%3Aissue+install) for a slew of installation problems related to gulp-sass.
37
80
38
81
##### Nav Bar Controls
39
-
If you don't have a need for some of the nav-bar tools in the patternlab frontend, you can turn them off in `config.json`.
82
+
If you don't have a need for some of the nav-bar tools in the Pattern Lab frontend, you can turn them off in `config.json`.
40
83
41
-
The current selection is as follows. It reflects support versus patternlab-php.
84
+
The current selection is as follows.
42
85
43
86
```
44
87
"ishControlsVisible": {
@@ -99,11 +142,20 @@ If you'd like to exclude an individual pattern you can do so by prepending the f
99
142
100
143
You can also exclude complete directories by prepending the directory name with an underscore, like: `/_experiment/...`
101
144
102
-
##### Verbose Mode
145
+
##### Debug Mode
103
146
`patternlab.json` is a file created for debugging purposes. Set `debug` to true in `.config.json` to see all the secrets.
104
147
105
-
##### Server
106
-
Running `grunt serve` will compile the patternlab front end and host it on <ahref="http://localhost:9001">http://localhost:9001</a> by default. Page will reload on any saved source code change.
148
+
##### Server & BrowserSync
149
+
Running `grunt serve` or `gulp serve` will compile the Pattern Lab frontend and host it by default on <ahref="http://localhost:3000">http://localhost:3000</a> via [BrowserSync](http://www.browsersync.io/docs/). After it starts, templates, `data.json`, and scss/css changes in your source code will be automatically injected into the page.
150
+
151
+
You'll notice that if you have this open across different browsers, we do our best to keep the frontend in sync, but there is a known issue with synced navigation using the main menu.
152
+
153
+
### Roadmap
154
+
155
+
156
+
A roadmap exists for Pattern Lab Node. Check it out [here](https://github.com/pattern-lab/patternlab-node/issues/134). The Node version of Pattern Lab is maintained by [@bmuenzenmeyer](https://twitter.com/bmuenzenmeyer) and contributors. Pull requests welcome, but please take a moment to read the [guidelines](https://github.com/pattern-lab/patternlab-node/blob/master/CONTRIBUTING.md).
157
+
158
+
Dave Olsen has also published the [specification](https://github.com/pattern-lab/the-spec/blob/draft/SPEC.md) for Pattern Lab ports. Development will be oriented toward compliance with this as the spec and the port mature together. Post v1 work will focus on other pattern engines and a plugin architecture.
107
159
108
160
### Advanced Pattern Library Features
109
161
@@ -190,37 +242,6 @@ This would compile to:
190
242
191
243
As you can see, it's a much easier way of linking patterns to one another.
192
244
193
-
194
-
===
195
-
196
-
The Node version of Pattern Lab is maintained by [@bmuenzenmeyer](https://twitter.com/bmuenzenmeyer) and contributors. Pull requests welcome, but please take a moment to read the [guidelines](https://github.com/pattern-lab/patternlab-node/blob/master/CONTRIBUTING.md).
197
-
198
-
### Upgrading
199
-
200
-
You can find some simple upgrade documenation in it's current home here (unreleased but confirmed to work): [https://github.com/pattern-lab/website/blob/dev/patternlabsite/docs/node/upgrading.md](https://github.com/pattern-lab/website/blob/dev/patternlabsite/docs/node/upgrading.md)
201
-
202
-
### ROADMAP
203
-
204
-
A roadmap exists for Pattern Lab Node. Check it out [here](https://github.com/pattern-lab/patternlab-node/issues/134)
205
-
206
-
Dave Olsen has also published the [specification](https://github.com/pattern-lab/the-spec/blob/draft/SPEC.md) for Pattern Lab ports. Development will be oriented toward compliance with this as the spec and the port mature together.
207
-
208
-
### Is Pattern Lab a Platform or a Build Tool?
209
-
210
-
A lot of good conversation has revolved around whether Pattern Lab is a platform or a tool in the toolbox, part of a larger solution. It's my goal to #1) adhere to the specification and #2) meet the needs of both use cases.
211
-
212
-
If you want to only build the patterns, alter your `Gruntfile.js` patternlab task to the following:
This will output compiled patterns to ./public/patterns/
219
-
220
-
### Where is the Gulp Version?
221
-
222
-
The core patternlab engine is free of any dependencies to grunt, allowing users to integrate with gulp if desired. Future efforts here will orient towards [this gulp implementation](https://github.com/oscar-g/patternlab-node/tree/dev-gulp) by [oscar-g](https://github.com/oscar-g).
0 commit comments