Project: pug-ruby - The Ruby Toolbox

🐶 Compile Jade and Pug from Ruby

About

pug-ruby is a gem that allows you to easily compile Jade and Pug templates from Ruby.

You can compile both Jade and Pug:

supports Jade 1.x.x.
supports Pug 2.x.x.

You can choose what compiler to use:

system compiler – compiler that is installed globally via NPM.
shipped compiler – compiler that is shipped with the gem as Web version.

Available versions of shipped compilers are listed below.

You can lock the Jade / Pug version:

NEEDED_JADE_VERSION = "1.9.2"

unless Jade.compiler.version == NEEDED_JADE_VERSION
  raise "Jade #{NEEDED_JADE_VERSION} needed. You have #{Jade.compiler.version}."
end

You can configure globally or per compilation:

Jade.config.pretty = true
Jade.compile "div Hello, Jade!", pretty: false

You can render template or compile it to the JavaScript function:

Jade.compile "div=greeting", locals: { greeting: "Hello, Jade!" } # => "<div>Hello, Jade!</div>"
Jade.compile "div=greeting", client: true                         # => "(function(jade) { function template(locals) {var buf = [];var jade_mixins = {};var jade_interp;;var locals_for_with = (locals || {});(function (greeting) {buf.push("<div>" + (jade.escape(null == (jade_interp = greeting) ? "" : jade_interp)) + "</div>");}.call(this,"greeting" in locals_for_with?locals_for_with.greeting:typeof greeting!=="undefined"?greeting:undefined));;return buf.join("");}; return template; }).call(this, jade);"

Advanced language features like include, extends and block are supported (only system compilers):

//- File: /var/www/app/views/header.jade
ul
  li: a(href='/') Home

//- File: /var/www/app/views/layout.jade
doctype html
html
  head
      title Application
  body
    header
      include ./header.jade

Jade.use :system

Jade.compile File.read("/var/www/app/views/layout.jade"), filename: "/var/www/app/views/layout.jade"
  # => "<!DOCTYPE html><html><head><title>Application</title></head><body><header><ul><li><a href="/">Home</a></li></ul></header></body></html>"

Installing gem

RubyGems users

Run gem install pug-ruby --version "~> 2.0.0".
Add require "pug-ruby" to your code.

Bundler users

Add to your Gemfile:

gem "pug-ruby", "~> 2.0.0"

Run bundle install.

Installing Jade

Only install if you want to use system compiler.

Install Jade globally via npm:

npm install --global jade

You may require sudo depending on your system.

Installing Pug

Only install if you want to use system compiler.

Install Pug globally via npm:

npm install --global pug

You may require sudo depending on your system.

Switching Jade / Pug version

The gem is shipped with different prebuilt versions of Jade and Pug. That prebuilt versions are Web version, e.g. they are limited to browser JavaScript. Advanced Jade / Pug features like includes, extends, block, and others require filesystem access. You will not be able to use that features while dealing with shipped Jade / Pug. Use system Jade / Pug in such cases.

Switching the version permanently:

Pug.use "2.0.0"      # You have just switched to shipped Pug 2.0.0.
Pug.compiler.version # Returns "2.0.0".

Pug.use :system      # You have just switched to system Pug.
Pug.compiler.version # Returns the version of your system-wide installed Pug.

Switching the version temporarily:

Jade.use "1.11.0" # You have just switched to shipped Jade 1.11.0.

Jade.use "1.9.2" do
  # You have just switched to shipped Jade 1.9.2.
  Jade.compiler.version # Returns "1.9.2".

  # Do you stuff.
end

# You have been switched back to the 1.11.0.
Jade.compiler.version # Returns "1.11.0".

Switching to the system Jade / Pug:

# Pass :system to switch to the system Jade / Pug.
Jade.use :system
Pug.use  :system

Shipped versions of Jade:

1.0.0
1.0.1
1.0.2
1.1.0
1.1.1
1.1.2
1.1.3
1.1.4
1.1.5
1.2.0
1.3.0
1.3.1
1.4.0
1.4.1
1.4.2
1.5.0
1.6.0
1.7.0
1.8.0
1.8.1
1.8.2
1.9.0
1.9.1
1.9.2
1.10.0
1.11.0

Shipped versions of Jade runtime:

1.0.0
1.0.1
1.0.2
1.1.0
1.1.1
1.1.2
1.1.3
1.1.4
1.1.5
1.2.0
1.3.0
1.3.1
1.4.0
1.4.1
1.4.2
1.5.0
1.6.0
1.7.0
1.8.0
1.8.1
1.8.2
1.9.0
1.9.1
1.9.2
1.10.0
1.11.0

Shipped versions of Pug:

2.0.0-beta1
2.0.0-beta2
2.0.0-beta3
2.0.0-beta4
2.0.0-beta5
2.0.0-beta6
2.0.0-beta7
2.0.0-beta8
2.0.0-beta9
2.0.0-beta10
2.0.0-beta11
2.0.0-beta12
2.0.0-rc.1
2.0.0-rc.2
2.0.0-rc.3
2.0.0-rc.4
2.0.1
2.0.2
2.0.3

Shipped versions of Pug runtime:

2.0.0
2.0.1
2.0.2

Configuring Jade / Pug

Accessing configuration:

Jade.config

Getting configuration options:

Jade.config.pretty  # => false
Jade.config.pretty? # => false

Setting configuration options:

Jade.config.pretty = true

Setting custom configuration options:

Jade.config.custom_option = "value"

Serializing configuration:

Jade.config.to_h
  # => { filename: nil, doctype: nil, pretty: false, self: false, compile_debug: false, globals: [], name: "template" }

The documentation for configuration options can be found here:

Pass an options to Jade#compile or Pug#compile as second argument to override global config:

Jade.compile "h1 Title\ndiv Content"
  # => "<h1>Title</h1><div>Content</div>"
  
Jade.compile "h1 Title\ndiv Content", pretty: true
  # => "<h1>Title</h1>\n<div>Content</div>"

Running tests

Install both Jade and Pug: npm install --global jade pug.
Install gem dependencies: bundle install.
Finally, run tests: bundle exec rake test.

pug-ruby

Development

Runtime