NOTE: this repo is required by contiv/contiv.github.io

HashiCorp Middleman Customizations

A wrapper around Middleman for HashiCorp's customizations.

Installation

Add this line to the Gemfile:

gem 'middleman-hashicorp', github: 'hashicorp/middleman-hashicorp'

And then run:

$ bundle

Usage

To generate a new site, follow the instructions in the Middleman docs. Then add the following line to your config.rb:

activate :hashicorp

If you are a HashiCorp employee and are deploying a HashiCorp middleman site, you will probably need to set some options. Here is an example from Packer:

activate :hashicorp do |h|
  h.name        = "packer"
  h.version     = "0.7.0"
  h.github_slug = "mitchellh/packer"

  # Disable some extensions
  h.minify_javascript = false
end

Almost all other Middleman options may be removed from the config.rb. See a HashiCorp project for examples.

Now just run:

$ middleman server

and you are off running!

Customizations

Default Options

• Syntax highlighting (via middleman-syntax) is automatically enabled
• Asset directories are organized like Rails:
  • assets/stylesheets
  • assets/javascripts
  • assets/images
  • assets/fonts
• The Markdown engine is redcarpet (see the section below on Markdown customizations)
• During development, live-reload is automatically enabled
• During build, css, javascript and HTML are minified
• During build, assets are hashed
• During build, gzipped assets are also created

Helpers

• latest_version - get the version specified in config.rb as version, but replicated here for use in views.

  latest_version #=> "1.0.0"

• system_icon - use vendored image assets for a system icon

  system_icon(:windows) #=> "<img src=\"/images/icons/....png\">"

• pretty_os - get the human name of the given operating system

  pretty_os(:darwin) => "Mac OS X"

• pretty_arch - get the arch out of an arch

  pretty_arch(:amd64) #=> "64-bit"

Markdown

This extension extends the redcarpet markdown processor to add some additional features:

• Autolinking of URLs
• Fenced code blocks
• Tables
• TOC data
• Strikethrough
• Superscript

In addition to "standard markdown", the custom markdown parser supports the following:

Auto-linking Anchor Tags

Sine the majority of HashiCorp's projects use the following syntax to define APIs, this extension automatically converts those to named anchor links:

- `api_method` - description

Outputs:

<ul>
  <li><a name="api_method" /><a href="#api_method"></a> - description</li>
</ul>

Any special characters are converted to an underscore (_).

Recursive Markdown Rendering

By default, the Markdown spec does not call for rendering markdown recursively inside of HTML. With this extension, it is valid:

<div class="center">
  This will **be bold**!
</div>

Bootstrap Alerts

There are 4 custom markdown extensions that automatically create Twitter Bootstrap-style alerts:

• => => success
• -> => info
• ~> => warning
• !> => danger

-> Hey, you should know...

<div class="alert alert-info" role="alert">
  <p>Hey, you should know...</p>
</div>

Of course you can use Markdown inside the block:

!> This is a **really** advanced topic!

<div class="alert alert-danger" role="alert">
  <p>This is a <strong>really</strong> advanced topic!</p>
</div>

Bootstrap

Twitter Bootstrap (3.x) is automatically bundled. Simply activate it it in your CSS and Javascript:

@import 'bootstrap-sprockets';
@import 'bootstrap';

//= require jquery
//= require bootstrap

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request