giles/README.html

a next-gen language watcher/compiler for pre-processed languages

<p>Giles wants you to stop writing HTML, CSS, and JS. </p>

<p>Giles is a static asset builder for a variety of useful markup languages.  Use Giles to develop with 
nextgen web tools and increase project momentum.</p>

<h2>Giles supports</h2>

<ul>
<li><a href="http://coffeescript.org/">CoffeeScript</a> - Incredible javascript compiler.  Everything just seems to work better with coffeescript. </li>
<li><a href="https://github.com/LearnBoost/stylus">Stylus</a> - Fantastic css compiler.  The variable/mixin support is extremely powerful.</li>
<li><a href="http://jade-lang.com/">Jade</a> - Cool HAML-like alternative to writing html.</li>
<li><a href="http://daringfireball.net/projects/markdown/">Markdown</a> - Markdown is the most intuitive markup language ever invented.</li>
<li>Your favorite language.  Add it and issue a pull request.</li>
</ul>

<h3>Giles is a command line tool and API for:</h3>

<ul>
<li>Developing.  Watch a directory using the <code>giles -s</code> command, and build files as they are requested.</li>
<li>Releasing.  Building static assets for deployment </li>
</ul>

<p>The goal of Giles is not to advocate a specific framework, rather to provide developers and designers
functionality in the languages of their choice.</p>

<h3>To install run</h3>

<p><code>bash
sudo npm install -g giles
</code></p>

<p><em>npm is available by installing <a href="http://nodejs.org">nodejs</a></em></p>

<h3>To build static assets, recursively</h3>

<p><code>bash
giles
</code></p>

<p><em>It will build every file into the same directory(views/index.jade will become views/index.html)</em></p>

<p><em>Giles ignores files that begin with '</em>' (underscore).  Use these for mixins, partials and etc. _</p>

<h3>To get help</h3>

<p><code>bash
giles -h
</code></p>

<p><em>If you ever need to run this, file a bug with me.</em></p>

<h3>To clean up</h3>

<p><code>bash
giles -c
</code>
<em>This will remove all files where generation is possible - IE: it will remove layout.html if you have a layout.jade.  Be safe out there!</em></p>

<!--
###To watch the current directory, recursively 
    giles -w
_Handles new files too.  It will work even if you re-arrange your whole project._

###To watch a specific directory, recursively 
    giles directory -w
_This compiles to the same directory as the asset._
###To build all assets recursively, outputting to a specific directory 
    giles -o build
-->

<h3>To ignore a directory, or multiple(will match recursively)</h3>

<p><code>bash
giles --ignore vendor,bin
</code></p>

<p><em>ignore defaults to node</em>modules,.git_</p>

<h3>To start a webserver on port 9000</h3>

<p><code>bash
giles -s -p 9000
</code>
<em>-p is optional, and will default to 2255 if not specified</em></p>

<h3>Environments</h3>

<pre><code>Note the flag -e is deprecated in favor of the NODE_ENV environment variable.
</code></pre>

<p>Environments are shortcuts that allow you to treat compilations differently. 
<em>giles defaults to null if unspecified.</em></p>

<p><code>
NODE_ENV=production giles &lt;dir&gt;
</code></p>

<p>Compile assets in <directory> in production mode.</p>

<p>Jade assets (and all compiled types that support local variables) can contain tests for the environment:</p>

<p><code>jade
- if(environment == 'production')
  #prodOnly content
</code></p>

<h1>API</h1>

<p>These examples are in coffeescript.</p>

<h3>Building with .js and giles (works with Jake or Cake)</h3>

<p>```coffeescript
srcDir = PATH<em>TO</em>SOURCE
options = {}</p>

<p>giles = require('giles')
giles.build(srcDir, options)
```</p>

<!--
### To watch with giles 
    srcDir = PATH_TO_SOURCE
    options = {}

    giles = require('giles')
    giles.watch(srcDir, options)
-->

<h3>To run the giles server</h3>

<p><code>coffeescript
giles = require('giles')
giles.server(dir, {port : 12345})
</code></p>

<p><em>Try it for a lightweight development mode</em></p>

<h3>To use giles connect/express module</h3>

<p><code>coffeescript
connect.use(giles.connect(srcDir))
</code></p>

<p>This connector will compile supported file types (index.jade will be compiled when index.html is requested).  It does not serve any files.</p>

<p><em>It is imperative that you place this before `connect.static'</em></p>

<h3>Adding a custom route</h3>

<p>By default giles creates a 1-1 map of template to generated page.  This allows you to use the same jade file with separate variables
to generate a dynamic page that is built into a finite amount of static targets.</p>

<p>```coffeescript</p>

<h1>This generates static files with the output file dynamicPage.html</h1>

<h1>locals is a list of variables available</h1>

<h1>to the .jade file when running this action</h1>

<p>locals = {name : "Martyn"}</p>

<p>giles.get '/dynamicPage.html', 'page.jade', locals
```</p>

<p><em>Then in page.jade</em></p>

<p><code>jade
!!!
head
  title = name
</code></p>

<h3>To add a compiler to giles</h3>

<p><code>coffeescript
coffee = require 'coffee-script'
giles.addCompiler ['.coffee', '.cs'], '.js', (contents, filename, output) -&gt;
  output(coffee.compile(contents, {}))
</code></p>

<h4>Or for stylus</h4>

<p><code>coffeescript
stylus = require 'stylus'
giles.addCompiler [".styl", ".stylus"], '.css', (contents, filename, output) -&gt;
  stylus.render contents, {filename: filename}, (err, css) -&gt;
    if err
      console.error "Could not render stylus file: "+filename
      console.error err
    else
      output(css)
</code></p>

<p><strong>Both of these compilers are already in giles and listed here for illustration purposes.</strong></p>

<h1>Changelog</h1>

<h3>v0.5.6</h3>

<ul>
<li>Added mocha specs around connect module</li>
<li>Merged issue with mime types from <a href="https://github.com/mbarzda/giles/commit/0edd714339d4287e4ca2443b800b2d165098d6ca">mbarzda</a></li>
</ul>

<h3>v0.5.5</h3>

<ul>
<li>Added giles -q (--quiet)</li>
</ul>

<h3>v0.5.4</h3>

<ul>
<li>Added giles -c (--clean)</li>
</ul>

<h3>v0.5.3</h3>

<ul>
<li>Added markdown</li>
<li>Fixed a bug in coffeescript generation</li>
</ul>

<h3>v0.5.2</h3>

<ul>
<li>Added -v flag to output version number</li>
</ul>

<h3>v0.5.1</h3>

<ul>
<li>Added -e flag for environments</li>
<li>Documentation slightly updated</li>
</ul>

<h3>v0.5.0</h3>

<ul>
<li>Added <code>giles.get("/route", sourceFile, locals)</code> for defining generated files</li>
<li>Added -s option which tells giles to start a webserver on port 2255</li>
<li>Added -p option to specify port of -s</li>
<li>Removed -w option, -s works better and more consistently</li>
</ul>

<h3>License</h3>

<p>Giles is available under the MIT license.  We hope you find it useful.  Please let us at 255 BITS know if you use it for something cool.</p>

<p><em>Into every generation a slayer is born: one girl in all the world, a Chosen One.  One born with the strength and skill
to fight the vampires, to stop the spread of their evil and swell of their numbers.</em></p>