more docs, narrow content file

harp.json

@@ -2,6 +2,7 @@
   "globals": {
     "site": {
       "language": "en",
+      "githubUrl": "https://github.com/evendev/harp-starter",
 
       "name": "Harp Starter"
     }

public/_layouts/narrow.jade

@@ -0,0 +1,6 @@
+extends container
+
+block container
+  .row
+    .col-sm-6.col-sm-offset-3
+      block narrow

public/index.jade

@@ -1,41 +1,116 @@
-extends _layouts/container
+extends _layouts/narrow
 
 block prepend title
   | #{ title } - 
 
-block container
-  h1 Welcome to 
-    code harp-starter
+block narrow
+  h1.page-header Welcome to 
+    code: a(href='#{ site.githubUrl }') harp-starter
 
-  p.lead An opinionated Harp boilerplate, with improvements that fit my typical Harp workflow.
+  p.lead An opinionated 
+    a(href='http://harpjs.com/') Harp
+    |  boilerplate, wrapped in a simple node script that allows use of other npm libraries.
+
+  hr
+
+  .row
+    .col-sm-6
+      p: strong Components
+      :markdown
+        - [Bootstrap](http://getbootstrap.com/) and [jQuery](https://jquery.com/)
+        - [Browserify](http://browserify.org/)
+        - [Font Awesome](http://fortawesome.github.io/Font-Awesome/)
+
+    .col-sm-6
+      p: strong External libraries
+      :markdown
+        - [Moment.js](http://momentjs.com/)
+        - [Underscore.js](http://underscorejs.org/)
+        - Easy to add other npm libraries
+
+  h2.page-header Justification
+
+  :markdown
+    Harp is an excellent and beautifully simple static site generator (and server). I most often use Harp to compile to static files, then sync em up to a simple server (like nginx or Apache). 
+
+    I've found myself repeating myself repeating myself time and time and time again, project after project after project. So I  put together this little boilerplate to save myself some future time.
+
+    Maybe it'll help you. Feel free to clone, fork, and send in pull requests.
+
+    ### Harp offers no support for external libraries in templates
+
+    One of the biggest complaints I've had about Harp is that I could never pull in other node modules, things like moment.js and underscore.js. In the past I've resorted to using libraries like these only in the browser. I found myself writing ugly and complicated iterations over JSON from `_data.json` files or formatting human-friendly dates only on the front-end via JavaScript. 
+
+    **Wouldn't it be great if I could use underscore or moment directly in my templates?!**
+
+    This is the main justification for this bolierplate. While I'm at it, I've included some other modules and resources that I typically use, like Bootstrap 3.x and Browserify. (They're easy enough to remove if you don't want them.)
+
+    [An article by Remy Sharp](https://remysharp.com/2014/09/30/wordpress-ghost-harp-pt2#use-of-special-helpers-inside-harp) clued me into a way of wrapping Harp's `compile` and `serve` features from my own node script, allowing me to make moment.js and underscore.js (and others) available to my Harp templates. Now (during the compile!) I can iterate using underscore and format dates nicely with moment.
+
+  h2.page-header Getting Started
+
+  :markdown
+    ### 1. Install a few modules globally:
+
+        npm install -g harp watchify browser-sync
+
+    ### 2a. Clone the git repo **OR** see 2b
+
+        git clone https://github.com/evendev/harp-starter my-project
+
+    ### 2b. Use the repo as a boilerplate
+
+        mkdir my-project && cd my-project
+        harp init -b evendev/harp-starter
+
+    ### 3. Start up the dev server
+
+        npm run dev
+
+    ### 4. Edit some files
+
+    - Edit `/harp.json` to change your global variables
+    - Edit `public/_layouts/*` as much as you need
+    - Edit this text in `public/index.jade`
+
+    ### 5. Build your site
+
+        npm run build
+
+  h2.page-header Shell Scripts
 
   :markdown
-    - [Bootstrap](http://getbootstrap.com/) and [jQuery](https://jquery.com/)
-    - [Browserify](http://browserify.org/)
-    - [Font Awesome](http://fortawesome.github.io/Font-Awesome/)
-    - **Support for using external libraries in templates:**
-      - [Moment.js](http://momentjs.com/)
-      - [Underscore.js](http://underscorejs.org/)
-      - Easily add your own!
+    Have a look at the `scripts` section in `package.json`. Everything should make pretty good sense to you.
+
+    The two scripts you'll run most often are:
 
-    ## Local Development Server
+    ### dev
 
-    - Copies fonts from bootstrap and font-awesome
-    - Watches `assets/js/app.js` for changes and recompiles to `assets/js/bundle.js`
-    - Serves via `harp server`
+    - Serves the site locally, on port 9000 by default (override this with `--port=XXXX`)
+    - Starts up `browser-sync`
+    - Watches `.js` changes and recompiles
 
-    ```shell
-    npm run dev
-    ```
 
-    ## Build
+        npm run dev
 
-    ```shell
-    npm run build
-    ```
+    ### build
 
-    ## Serve
+    Compiles the site to static files in `/www`
 
-    ```shell
-    npm run serve [--port=9000]
-    ```
+        npm run build
+
+  h2.page-header Layouts
+
+  p A note on layouts:
+
+  :markdown
+    For lots of my projects, I end up having to avoid Harp's built in `_layout` and `partial()` features, as I find I need more power and flexibility. 
+
+    If you use **both** Jade layouts and `include`s and Harp's `_layout`s and `partial()` features, you'll probably encounter path issues and errors: One expects relative paths, while the other expects root-relative paths. I avoid this by exclusively using native Jade features. This isn't to say that you can't throw a `partial()` call in there or that you can't use a `_layout` in a subdirectory. Just know that you may have to jump through some hoops to get the paths just right when using both native Jade and Harp's built-in layout features.
+
+    You're welcome to wipe out the `_layouts` directory and modify the `_layout.jade` file if you'd rather use Harp's built in features.
+
+  h2.page-header EJS
+
+  :markdown
+    I haven't tried this using EJS, but I don't see why it wouldn't work.