Awesome
🐶 Compile Jade and Pug from Ruby
<img width="49.710808069%" alt="jade" align="left" src="https://user-images.githubusercontent.com/7421323/29007509-4fb4e004-7b0d-11e7-9b21-6bdd98a24344.png"> <img width="48.035162854%" alt="pug" src="https://user-images.githubusercontent.com/7421323/29007510-4fcdb638-7b0d-11e7-80c7-e3c49434ca8a.png">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:
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:
- Official Jade website (Web Archive only)
- Jade CLI utility reference
- Official Pug website
- Pug CLI utility reference
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
.