Merge pull request #576 from richardvenneman/readme-headings

Author: rafaelfranca

README.md

@@ -5,7 +5,7 @@ manipulating giant hash structures. This is particularly helpful when the
 generation process is fraught with conditionals and loops. Here's a simple
 example:
 
-``` ruby
+```ruby
 # app/views/messages/show.json.jbuilder
 
 json.content format_content(@message.content)
@@ -31,7 +31,7 @@ end
 
 This will build the following structure:
 
-``` javascript
+```javascript
 {
   "content": "<p>This is <i>serious</i> monkey business</p>",
   "created_at": "2011-10-29T20:45:28-05:00",
@@ -57,20 +57,23 @@ This will build the following structure:
 }
 ```
 
+## Dynamically Defined Attributes
+
 To define attribute and structure names dynamically, use the `set!` method:
 
-``` ruby
+```ruby
 json.set! :author do
   json.set! :name, 'David'
 end
 
 # => {"author": { "name": "David" }}
 ```
 
+## Merging Existing Hash or Array
 
 To merge existing hash or array to current context:
 
-``` ruby
+```ruby
 hash = { author: { name: "David" } }
 json.post do
   json.title "Merge HOWTO"
@@ -80,9 +83,11 @@ end
 # => "post": { "title": "Merge HOWTO", "author": { "name": "David" } }
 ```
 
-Top level arrays can be handled directly.  Useful for index and other collection actions.
+## Top Level Arrays
+
+Top level arrays can be handled directly. Useful for index and other collection actions.
 
-``` ruby
+```ruby
 # @comments = @post.comments
 
 json.array! @comments do |comment|
@@ -98,16 +103,20 @@ end
 # => [ { "body": "great post...", "author": { "first_name": "Joe", "last_name": "Bloe" }} ]
 ```
 
+## Array Attributes
+
 You can also extract attributes from array directly.
 
-``` ruby
+```ruby
 # @people = People.all
 
 json.array! @people, :id, :name
 
 # => [ { "id": 1, "name": "David" }, { "id": 2, "name": "Jamie" } ]
 ```
 
+## Plain Arrays
+
 To make a plain array without keys, construct and pass in a standard Ruby array.
 
 ```ruby
@@ -118,6 +127,8 @@ json.people my_array
 # => "people": [ "David", "Jamie" ]
 ```
 
+## Child Objects
+
 You don't always have or need a collection when building an array.
 
 ```ruby
@@ -135,9 +146,11 @@ end
 # => { "people": [ { "id": 1, "name": "David" }, { "id": 2, "name": "Jamie" } ] }
 ```
 
-Jbuilder objects can be directly nested inside each other.  Useful for composing objects.
+## Nested Jbuilder Objects
+
+Jbuilder objects can be directly nested inside each other. Useful for composing objects.
 
-``` ruby
+```ruby
 class Person
   # ... Class Definition ... #
   def to_builder
@@ -163,11 +176,13 @@ company.to_builder.target!
 # => {"name":"Doodle Corp","president":{"name":"John Stobs","age":58}}
 ```
 
+## Rails Integration
+
 You can either use Jbuilder stand-alone or directly as an ActionView template
 language. When required in Rails, you can create views à la show.json.jbuilder
 (the json is already yielded):
 
-``` ruby
+```ruby
 # Any helpers available to views are available to the builder
 json.content format_content(@message.content)
 json.(@message, :created_at, :updated_at)
@@ -183,6 +198,8 @@ if current_user.admin?
 end
 ```
 
+## Partials
+
 You can use partials as well. The following will render the file
 `views/comments/_comments.json.jbuilder`, and set a local variable
 `comments` with all this message's comments, which you can use inside
@@ -215,15 +232,15 @@ then the object is passed to the partial as the variable `some_symbol`.
 Be sure not to confuse the `as:` option to mean nesting of the partial. For example:
 
 ```ruby
- # Use the default `views/comments/_comment.json.jbuilder`, putting @comment as the comment local variable.
- # Note, `comment` attributes are "inlined".
- json.partial! @comment, as: :comment
+# Use the default `views/comments/_comment.json.jbuilder`, putting @comment as the comment local variable.
+# Note, `comment` attributes are "inlined".
+json.partial! @comment, as: :comment
 ```
 
 is quite different from:
 
 ```ruby
- # comment attributes are nested under a "comment" property
+# comment attributes are nested under a "comment" property
 json.comment do
   json.partial! "/comments/comment.json.jbuilder", comment: @comment
 end
@@ -239,10 +256,11 @@ json.partial! 'sub_template', locals: { user: user }
 json.partial! 'sub_template', user: user
 ```
 
+## Null Values
 
 You can explicitly make Jbuilder object return null if you want:
 
-``` ruby
+```ruby
 json.extract! @post, :id, :title, :content, :published_at
 json.author do
   if @post.anonymous?
@@ -305,7 +323,7 @@ This will include both records as part of the cache key and updating either of t
 Keys can be auto formatted using `key_format!`, this can be used to convert
 keynames from the standard ruby_format to camelCase:
 
-``` ruby
+```ruby
 json.key_format! camelize: :lower
 json.first_name 'David'
 
@@ -315,15 +333,15 @@ json.first_name 'David'
 You can set this globally with the class method `key_format` (from inside your
 environment.rb for example):
 
-``` ruby
+```ruby
 Jbuilder.key_format camelize: :lower
 ```
 
 By default, key format is not applied to keys of hashes that are
 passed to methods like `set!`, `array!` or `merge!`. You can opt into
 deeply transforming these as well:
 
-``` ruby
+```ruby
 json.key_format! camelize: :lower
 json.deep_format_keys!
 json.settings([{some_value: "abc"}])
@@ -334,7 +352,7 @@ json.settings([{some_value: "abc"}])
 You can set this globally with the class method `deep_format_keys` (from inside your
 environment.rb for example):
 
-``` ruby
+```ruby
 Jbuilder.deep_format_keys true
 ```
 
@@ -350,4 +368,5 @@ features and discuss issues.
 See [CONTRIBUTING](CONTRIBUTING.md).
 
 ## License
+
 Jbuilder is released under the [MIT License](http://www.opensource.org/licenses/MIT).