Middleman-Syntax

middleman-syntax is an extension for the Middleman static site generator that adds syntax highlighting via Rouge.

Installation

If you're just getting started, install the middleman gem and generate a new project:

gem install middleman
middleman init MY_PROJECT

If you already have a Middleman project: Add gem "middleman-syntax" to your Gemfile and run bundle install.

This plugin will not work on Ruby 1.8! Rouge requires 1.9+, so we do too.

Configuration

activate :syntax

You can also pass options to Rouge:

activate :syntax,
         :linenos => 'inline',
         :anchorlinenos => true,
         :linenostart => 2

Helper

The extension adds a new code helper to Middleman that you can use from your templates:

<% code("ruby") do %>
def my_cool_method(message)
  puts message
end
<% end %>

That'll produce syntax-highlighted HTML wrapped in <pre class="highlight ruby">.

CSS

On a default (i.e. unstyled) Middleman project, it will appear as if middleman-syntax isn't working, since obviously no CSS has been applied to color your code. You can use any Pygments-compatible stylesheet to style your code.

You can also let Rouge generate some CSS for you by creating a new stylesheet with a .css.erb extension in your Middleman project, and then including:

<%= Rouge::Themes::ThankfulEyes.render(:scope => '.highlight') %>

Rouge has ThankfulEyes, Colorful, Github, Base16, Base16::Solarized (like Octopress), and Base16::Monokai themes.

Markdown

The extension also makes code blocks in Markdown produce highlighted code. Make sure you're using RedCarpet or Kramdown as your Markdown engine (in config.rb):

set :markdown_engine, :redcarpet
set :markdown, :fenced_code_blocks => true, :smartypants => true

## OR

set :markdown_engine, :kramdown

Now your Markdown will work just like it does on GitHub - you can write something like this with Redcarpet:

```ruby
def my_cool_method(message)
  puts message
end
```

or with Kramdown:

~~~ ruby
def my_cool_method(message)
  puts message
end
~~~

Indentation Problems

Some templating languages, like Haml, will indent your HTML for you, which will mess up code formatted in <pre> tags. When using Haml, either use the find_and_preserve helper, the :preserve filter, or add set :haml, { ugly: true } in your config.rb to turn off Haml's automatic indentation.

Build & Dependency Status

Community

The official community forum is available at: http://forum.middlemanapp.com

Bug Reports

Github Issues are used for managing bug reports and feature requests. If you run into issues, please search the issues and submit new problems: https://github.com/middleman/middleman-syntax/issues

The best way to get quick responses to your issues and swift fixes to your bugs is to submit detailed bug reports, include test cases and respond to developer questions in a timely manner. Even better, if you know Ruby, you can submit Pull Requests containing Cucumber Features which describe how your feature should work or exploit the bug you are submitting.

How to Run Cucumber Tests

1. Checkout Repository: git clone https://github.com/middleman/middleman-syntax.git
2. Install Bundler: gem install bundler
3. Run bundle install inside the project root to install the gem dependencies.
4. Run test cases: bundle exec rake test

Donate

Click here to lend your support to Middleman

License

Copyright (c) 2012-2013 Benjamin Hollis. MIT Licensed, see LICENSE for details.