4 files changed, 57 insertions, 6 deletions
diff --git a/guides/source/action_controller_overview.md b/guides/source/action_controller_overview.md
index 222d86afe9..5b5f53c9be 100644
--- a/guides/source/action_controller_overview.md
+++ b/guides/source/action_controller_overview.md
@@ -1088,7 +1088,7 @@ class ApplicationController < ActionController::Base
   private
 
     def record_not_found
-      render text: "404 Not Found", status: 404
+      render plain: "404 Not Found", status: 404
     end
 end
 ```
diff --git a/guides/source/getting_started.md b/guides/source/getting_started.md
index 53d2a9b55b..a16b9ac8da 100644
--- a/guides/source/getting_started.md
+++ b/guides/source/getting_started.md
@@ -608,7 +608,7 @@ look like, change the `create` action to this:
 
 ```ruby
 def create
-  render text: params[:article].inspect
+  render plain: params[:article].inspect
 end
 ```
 
diff --git a/guides/source/layouts_and_rendering.md b/guides/source/layouts_and_rendering.md
index 93e25d619e..66ed6f2e08 100644
--- a/guides/source/layouts_and_rendering.md
+++ b/guides/source/layouts_and_rendering.md
@@ -236,15 +236,34 @@ render inline: "xml.p {'Horrid coding practice!'}", type: :builder
 
 #### Rendering Text
 
-You can send plain text - with no markup at all - back to the browser by using the `:text` option to `render`:
+You can send plain text - with no markup at all - back to the browser by using
+the `:plain` option to `render`:
 
 ```ruby
-render text: "OK"
+render plain: "OK"
 ```
 
-TIP: Rendering pure text is most useful when you're responding to Ajax or web service requests that are expecting something other than proper HTML.
+TIP: Rendering pure text is most useful when you're responding to Ajax or web
+service requests that are expecting something other than proper HTML.
 
-NOTE: By default, if you use the `:text` option, the text is rendered without using the current layout. If you want Rails to put the text into the current layout, you need to add the `layout: true` option.
+NOTE: By default, if you use the `:plain` option, the text is rendered without
+using the current layout. If you want Rails to put the text into the current
+layout, you need to add the `layout: true` option.
+
+#### Rendering HTML
+
+You can send a HTML string back to the browser by using the `:html` option to
+`render`:
+
+```ruby
+render html: "<strong>Not Found</strong>".html_safe
+```
+
+TIP: This is useful when you're rendering a small snippet of HTML code.
+However, you might want to consider moving it to a template file if the markup
+is complex.
+
+NOTE: This option will escape HTML entities if the string is not html safe.
 
 #### Rendering JSON
 
@@ -276,6 +295,19 @@ render js: "alert('Hello Rails');"
 
 This will send the supplied string to the browser with a MIME type of `text/javascript`.
 
+#### Rendering raw body
+
+You can send a raw content back to the browser, without setting any content
+type, by using the `:body` option to `render`:
+
+```ruby
+render body: "raw"
+```
+
+TIP: This option should be used only if you explicitly want the content type to
+be unset. Using `:plain` or `:html` might be more appropriate in most of the
+time.
+
 #### Options for `render`
 
 Calls to the `render` method generally accept four options:
diff --git a/guides/source/upgrading_ruby_on_rails.md b/guides/source/upgrading_ruby_on_rails.md
index 76722c9ea9..a8b7c9d492 100644
--- a/guides/source/upgrading_ruby_on_rails.md
+++ b/guides/source/upgrading_ruby_on_rails.md
@@ -329,6 +329,25 @@ User.inactive
 # SELECT "users".* FROM "users" WHERE "users"."state" = 'inactive'
 ```
 
+### Rendering content from string
+
+Rails 4.1 introduces `:plain`, `:html`, and `:body` options to `render`. Those
+options are now the preferred way to render string-based content, as it allows
+you to specify which content type you want the response sent as.
+
+* `render :plain` will set the content type to `text/plain`
+* `render :html` will set the content type to `text/html`
+* `render :body` will *not* set the content type header.
+
+From the security standpoint, if you don't expect to have any markup in your
+response body, you should be using `render :plain` as most browsers will escape
+unsafe content in the response for you.
+
+We will be deprecating the use of `render :text` in a future version. So please
+start using the more precise `:plain:`, `:html`, and `:body` options instead.
+Using `render :text` may pose a security risk, as the content is sent as
+`text/html`.
+
 Upgrading from Rails 3.2 to Rails 4.0
 -------------------------------------