features docs
This commit is contained in:
Thomas Reynolds
parent
c00c47eeb3
commit
48d2956a57
|
|
@ -1,168 +0,0 @@
|
||||||
<!DOCTYPE html>
|
|
||||||
<html>
|
|
||||||
<head>
|
|
||||||
<meta http-equiv="content-type" content="text/html;charset=utf-8">
|
|
||||||
<title>middleman.rb</title>
|
|
||||||
<link rel="stylesheet" href="http://jashkenas.github.com/docco/resources/docco.css">
|
|
||||||
</head>
|
|
||||||
<body>
|
|
||||||
<div id='container'>
|
|
||||||
<div id="background"></div>
|
|
||||||
<table cellspacing=0 cellpadding=0>
|
|
||||||
<thead>
|
|
||||||
<tr>
|
|
||||||
<th class=docs><h1>middleman.rb</h1></th>
|
|
||||||
<th class=code></th>
|
|
||||||
</tr>
|
|
||||||
</thead>
|
|
||||||
<tbody>
|
|
||||||
<tr id='section-1'>
|
|
||||||
<td class=docs>
|
|
||||||
<div class="octowrap">
|
|
||||||
<a class="octothorpe" href="#section-1">#</a>
|
|
||||||
</div>
|
|
||||||
<p> Middleman is a static site renderer that provides all the conveniences of
|
|
||||||
a modern web stack, like Ruby on Rails, while remaining focused on building
|
|
||||||
the fastest, most-professional sites possible</p>
|
|
||||||
|
|
||||||
<p> Install Middleman:</p>
|
|
||||||
|
|
||||||
<pre><code> gem install middleman
|
|
||||||
</code></pre>
|
|
||||||
|
|
||||||
<p> To accomplish its goals, Middleman supports provides access to:</p>
|
|
||||||
|
|
||||||
<h3>Command-line tools:</h3>
|
|
||||||
|
|
||||||
<ul>
|
|
||||||
<li><strong>mm-init</strong>: A tool for creating to new static sites.</li>
|
|
||||||
<li><strong>mm-server</strong>: A tool for rapidly developing your static site.</li>
|
|
||||||
<li><strong>mm-build</strong>: A tool for exporting your site into optimized HTML, CSS & JS.</li>
|
|
||||||
</ul>
|
|
||||||
|
|
||||||
|
|
||||||
<h3>Tons of templating languages including:</h3>
|
|
||||||
|
|
||||||
<ul>
|
|
||||||
<li>ERB (.erb)</li>
|
|
||||||
<li>Interpolated String (.str)</li>
|
|
||||||
<li>Sass (.sass)</li>
|
|
||||||
<li>Scss (.scss)</li>
|
|
||||||
<li>Haml (.haml)</li>
|
|
||||||
<li>Sass (.sass)</li>
|
|
||||||
<li>Less CSS (.less)</li>
|
|
||||||
<li>Builder (.builder)</li>
|
|
||||||
<li>Liquid (.liquid)</li>
|
|
||||||
<li>RDiscount (.markdown)</li>
|
|
||||||
<li>RedCloth (.textile)</li>
|
|
||||||
<li>RDoc (.rdoc)</li>
|
|
||||||
<li>Radius (.radius)</li>
|
|
||||||
<li>Markaby (.mab)</li>
|
|
||||||
<li>Nokogiri (.nokogiri)</li>
|
|
||||||
<li>Mustache (.mustache)</li>
|
|
||||||
<li>CoffeeScript (.coffee)</li>
|
|
||||||
</ul>
|
|
||||||
|
|
||||||
|
|
||||||
<h3>Compile-time Optimiztions</h3>
|
|
||||||
|
|
||||||
<ul>
|
|
||||||
<li>Javascript Minifiers: YUI, Google Closure & UglifyJS</li>
|
|
||||||
<li>Smush.it Image Compression</li>
|
|
||||||
<li>CSS Minification</li>
|
|
||||||
</ul>
|
|
||||||
|
|
||||||
|
|
||||||
<h3>Robust Extensions:</h3>
|
|
||||||
|
|
||||||
<p> Add your own runtime and build-time features!</p>
|
|
||||||
|
|
||||||
<h3>Next Steps:</h3>
|
|
||||||
|
|
||||||
<ul>
|
|
||||||
<li><a href="http://middlemanapp.com">Visit the website</a></li>
|
|
||||||
<li><a href="https://github.com/tdreyno/middleman/wiki">Read the wiki</a></li>
|
|
||||||
<li><a href="http://groups.google.com/group/middleman-users">Email the users group</a></li>
|
|
||||||
<li><a href="https://github.com/tdreyno/middleman/issues">Submit bug reports</a></li>
|
|
||||||
</ul>
|
|
||||||
</td>
|
|
||||||
<td class=code>
|
|
||||||
<div class='highlight'><pre></pre></div>
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr id='section-2'>
|
|
||||||
<td class=docs>
|
|
||||||
<div class="octowrap">
|
|
||||||
<a class="octothorpe" href="#section-2">#</a>
|
|
||||||
</div>
|
|
||||||
<p> Setup out load paths</p>
|
|
||||||
</td>
|
|
||||||
<td class=code>
|
|
||||||
<div class='highlight'><pre><span class="n">libdir</span> <span class="o">=</span> <span class="no">File</span><span class="o">.</span><span class="n">dirname</span><span class="p">(</span><span class="bp">__FILE__</span><span class="p">)</span>
|
|
||||||
<span class="vg">$LOAD_PATH</span><span class="o">.</span><span class="n">unshift</span><span class="p">(</span><span class="n">libdir</span><span class="p">)</span> <span class="k">unless</span> <span class="vg">$LOAD_PATH</span><span class="o">.</span><span class="n">include?</span><span class="p">(</span><span class="n">libdir</span><span class="p">)</span></pre></div>
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr id='section-3'>
|
|
||||||
<td class=docs>
|
|
||||||
<div class="octowrap">
|
|
||||||
<a class="octothorpe" href="#section-3">#</a>
|
|
||||||
</div>
|
|
||||||
<p> Require Rubygems (probably not necessary)</p>
|
|
||||||
</td>
|
|
||||||
<td class=code>
|
|
||||||
<div class='highlight'><pre><span class="nb">require</span> <span class="s1">'rubygems'</span></pre></div>
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr id='section-4'>
|
|
||||||
<td class=docs>
|
|
||||||
<div class="octowrap">
|
|
||||||
<a class="octothorpe" href="#section-4">#</a>
|
|
||||||
</div>
|
|
||||||
<p> Top-level Middleman object</p>
|
|
||||||
</td>
|
|
||||||
<td class=code>
|
|
||||||
<div class='highlight'><pre><span class="k">module</span> <span class="nn">Middleman</span></pre></div>
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr id='section-5'>
|
|
||||||
<td class=docs>
|
|
||||||
<div class="octowrap">
|
|
||||||
<a class="octothorpe" href="#section-5">#</a>
|
|
||||||
</div>
|
|
||||||
<p> Auto-load modules on-demand</p>
|
|
||||||
</td>
|
|
||||||
<td class=code>
|
|
||||||
<div class='highlight'><pre> <span class="nb">autoload</span> <span class="ss">:Server</span><span class="p">,</span> <span class="s2">"middleman/server"</span>
|
|
||||||
</pre></div>
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr id='section-6'>
|
|
||||||
<td class=docs>
|
|
||||||
<div class="octowrap">
|
|
||||||
<a class="octothorpe" href="#section-6">#</a>
|
|
||||||
</div>
|
|
||||||
<p> Custom Renderers</p>
|
|
||||||
</td>
|
|
||||||
<td class=code>
|
|
||||||
<div class='highlight'><pre> <span class="k">module</span> <span class="nn">Renderers</span>
|
|
||||||
<span class="nb">autoload</span> <span class="ss">:Haml</span><span class="p">,</span> <span class="s2">"middleman/renderers/haml"</span>
|
|
||||||
<span class="nb">autoload</span> <span class="ss">:Sass</span><span class="p">,</span> <span class="s2">"middleman/renderers/sass"</span>
|
|
||||||
<span class="k">end</span></pre></div>
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr id='section-7'>
|
|
||||||
<td class=docs>
|
|
||||||
<div class="octowrap">
|
|
||||||
<a class="octothorpe" href="#section-7">#</a>
|
|
||||||
</div>
|
|
||||||
<p> Features API</p>
|
|
||||||
|
|
||||||
</td>
|
|
||||||
<td class=code>
|
|
||||||
<div class='highlight'><pre> <span class="nb">autoload</span> <span class="ss">:Features</span><span class="p">,</span> <span class="s2">"middleman/features"</span>
|
|
||||||
<span class="k">end</span></pre></div>
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
</table>
|
|
||||||
</div>
|
|
||||||
</body>
|
|
||||||
|
|
@ -1,18 +1,81 @@
|
||||||
|
# Middleman provides an extension API which allows you to hook into the
|
||||||
|
# lifecycle of a page request, or static build, and manipulate the output.
|
||||||
|
# Internal to Middleman, these extensions are called "features," but we use
|
||||||
|
# the exact same API as is made available to the public.
|
||||||
|
#
|
||||||
|
# A Middleman extension looks like this:
|
||||||
|
#
|
||||||
|
# module MyExtension
|
||||||
|
# class << self
|
||||||
|
# def registered(app)
|
||||||
|
# # My Code
|
||||||
|
# end
|
||||||
|
# end
|
||||||
|
# end
|
||||||
|
#
|
||||||
|
# In your `config.rb`, you must load your extension (if it is not defined in
|
||||||
|
# that file) and call `activate`.
|
||||||
|
#
|
||||||
|
# require "my_extension"
|
||||||
|
# activate MyExtension
|
||||||
|
#
|
||||||
|
# This will call the `registered` method in your extension and provide you
|
||||||
|
# with the `app` parameter which is a Middleman::Server context. From here
|
||||||
|
# you can choose to respond to requests for certain paths or simply attach
|
||||||
|
# Rack middleware to the stack.
|
||||||
|
#
|
||||||
|
# The built-in features cover a wide range of functions. Some provide helper
|
||||||
|
# methods to use in your views. Some modify the output on-the-fly. And some
|
||||||
|
# apply computationally-intensive changes to your final build files.
|
||||||
|
|
||||||
module Middleman::Features
|
module Middleman::Features
|
||||||
|
|
||||||
|
# RelativeAssets allow any asset path in dynamic templates to be either
|
||||||
|
# relative to the root of the project or use an absolute URL.
|
||||||
autoload :RelativeAssets, "middleman/features/relative_assets"
|
autoload :RelativeAssets, "middleman/features/relative_assets"
|
||||||
autoload :AssetHost, "middleman/features/asset_host"
|
|
||||||
autoload :CacheBuster, "middleman/features/cache_buster"
|
|
||||||
autoload :DefaultHelpers, "middleman/features/default_helpers"
|
|
||||||
autoload :AutomaticImageSizes, "middleman/features/automatic_image_sizes"
|
|
||||||
autoload :UglyHaml, "middleman/features/ugly_haml"
|
|
||||||
autoload :MinifyCss, "middleman/features/minify_css"
|
|
||||||
autoload :MinifyJavascript, "middleman/features/minify_javascript"
|
|
||||||
autoload :Slickmap, "middleman/features/slickmap"
|
|
||||||
autoload :SmushPngs, "middleman/features/smush_pngs"
|
|
||||||
autoload :CodeRay, "middleman/features/code_ray"
|
|
||||||
autoload :Lorem, "middleman/features/lorem"
|
|
||||||
# autoload :LiveReload, "middleman/features/live_reload"
|
|
||||||
|
|
||||||
|
# AssetHost allows you to setup multiple domains to host your static assets.
|
||||||
|
# Calls to asset paths in dynamic templates will then rotate through each of
|
||||||
|
# the asset servers to better spread the load.
|
||||||
|
autoload :AssetHost, "middleman/features/asset_host"
|
||||||
|
|
||||||
|
# CacheBuster adds a query string to assets in dynamic templates to avoid
|
||||||
|
# browser caches failing to update to your new content.
|
||||||
|
autoload :CacheBuster, "middleman/features/cache_buster"
|
||||||
|
|
||||||
|
# DefaultHelpers are the built-in dynamic template helpers.
|
||||||
|
autoload :DefaultHelpers, "middleman/features/default_helpers"
|
||||||
|
|
||||||
|
# AutomaticImageSizes inspects the images used in your dynamic templates and
|
||||||
|
# automatically adds width and height attributes to their HTML elements.
|
||||||
|
autoload :AutomaticImageSizes, "middleman/features/automatic_image_sizes"
|
||||||
|
|
||||||
|
# UglyHaml enables the non-indented output format from Haml templates. Useful
|
||||||
|
# for somewhat obfuscating the output and hiding the fact that you're using Haml.
|
||||||
|
autoload :UglyHaml, "middleman/features/ugly_haml"
|
||||||
|
|
||||||
|
# MinifyCss uses the YUI compressor to shrink CSS files
|
||||||
|
autoload :MinifyCss, "middleman/features/minify_css"
|
||||||
|
|
||||||
|
# MinifyJavascript uses the YUI compressor to shrink JS files
|
||||||
|
autoload :MinifyJavascript, "middleman/features/minify_javascript"
|
||||||
|
|
||||||
|
# Slickmap (http://astuteo.com/slickmap/) is a beautiful sitemap tool which
|
||||||
|
# will attempt to generate a `sitemap.html` file from your project.
|
||||||
|
autoload :Slickmap, "middleman/features/slickmap"
|
||||||
|
|
||||||
|
# SmushPngs uses Yahoo's Smush.it API to compresses PNGs and JPGs. Often times
|
||||||
|
# the service can decrease the size of Photoshop-exported images by 30-50%
|
||||||
|
autoload :SmushPngs, "middleman/features/smush_pngs"
|
||||||
|
|
||||||
|
# CodeRay is a syntax highlighter.
|
||||||
|
autoload :CodeRay, "middleman/features/code_ray"
|
||||||
|
|
||||||
|
# Lorem provides a handful of helpful prototyping methods to generate words,
|
||||||
|
# paragraphs, fake images, names and email addresses.
|
||||||
|
autoload :Lorem, "middleman/features/lorem"
|
||||||
|
|
||||||
|
# The Feature API is itself a Feature. Mind blowing!
|
||||||
class << self
|
class << self
|
||||||
def registered(app)
|
def registered(app)
|
||||||
app.extend ClassMethods
|
app.extend ClassMethods
|
||||||
|
|
@ -21,13 +84,23 @@ module Middleman::Features
|
||||||
end
|
end
|
||||||
|
|
||||||
module ClassMethods
|
module ClassMethods
|
||||||
|
# This method is available in the project's `config.rb`.
|
||||||
|
# It takes a underscore-separated symbol, finds the appropriate
|
||||||
|
# feature module and includes it.
|
||||||
|
#
|
||||||
|
# activate :lorem
|
||||||
|
#
|
||||||
|
# Alternatively, you can pass in a Middleman feature module directly.
|
||||||
|
#
|
||||||
|
# activate MyFeatureModule
|
||||||
def activate(feature_name)
|
def activate(feature_name)
|
||||||
mod_name = feature_name.to_s.camelize
|
feature_name = feature_name.to_s if feature_name.class == Symbol
|
||||||
if Middleman::Features.const_defined?(mod_name)
|
feature_name = Middleman::Features.const_get(feature_name.camelize) if feature_name.class == String if Middleman::Features.const_defined?(mod_name)
|
||||||
register Middleman::Features.const_get(mod_name)
|
|
||||||
end
|
register feature_name
|
||||||
end
|
end
|
||||||
|
|
||||||
|
# Deprecated API. Please use `activate` instead.
|
||||||
def enable(feature_name)
|
def enable(feature_name)
|
||||||
$stderr.puts "Warning: Feature activation has been renamed from enable to activate"
|
$stderr.puts "Warning: Feature activation has been renamed from enable to activate"
|
||||||
activate(feature_name)
|
activate(feature_name)
|
||||||
|
|
|
||||||
|
|
@ -39,5 +39,6 @@ Gem::Specification.new do |s|
|
||||||
s.add_runtime_dependency("less", ["~> 1.2.0"])
|
s.add_runtime_dependency("less", ["~> 1.2.0"])
|
||||||
s.add_development_dependency("cucumber", ["~> 0.10.0"])
|
s.add_development_dependency("cucumber", ["~> 0.10.0"])
|
||||||
s.add_development_dependency("rspec", [">= 0"])
|
s.add_development_dependency("rspec", [">= 0"])
|
||||||
|
s.add_development_dependency("rocco", [">= 0"])
|
||||||
end
|
end
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue