For a perhaps better solution for .html.md files that also supports embedding Erb in your Markdown, check out @wjbuys's answer on Stackoverflow.
This gem allows you to write static Rails views and partials using the Markdown syntax. No more editing prose in HTML!
Add the following to your Gemfile:
gem 'markdown-rails'
Now add views or partials ending in .md
or .markdown
.
In app/views/home/about.html.md
:
# About This Site
*Markdown code goes here ...*
Keep in mind that unlike static files dropped in public
, you still need a
matching route, such as get ':action', :controller => :home
, to route
/about
to home#about
.
In app/views/posts/edit.html.erb
:
<form>... dynamic code goes here ...</form>
<div class="help">
<%= render :partial => "posts/edit_help" %>
</div>
In app/views/posts/_edit_help.html.md
:
## How To Edit
This text is written in **Markdown**. :-)
Note: If you are including Markdown partials from a Haml view, <pre>
blocks
inside your Markdown may be indented when Haml is not in "ugly" (production)
mode,
causing leading white-space to appear in development mode. To fix this, set
Haml::Template.options[:ugly] = true
.
By default markdown-rails uses the
RDiscount parser. You can change this
by calling config.render
like so:
MarkdownRails.configure do |config|
config.render do |markdown_source|
# Return compiled HTML here ...
end
end
You might in particular want to use
Redcarpet, which allows you to enable
various aspects of GitHub Flavored
Markdown through its
parser options. To do so, add the redcarpet
gem to your Gemfile, and add the
following into a config/initializers/markdown.rb
file:
MarkdownRails.configure do |config|
markdown = Redcarpet::Markdown.new(Redcarpet::Render::HTML,
:fenced_code_blocks => true,
:autolink => true,
... etc ...)
config.render do |markdown_source|
markdown.render(markdown_source)
end
end
Despite Markdown being a static language, you should not use this gem to process untrusted Markdown views (or partials). In other words, do not add Markdown views from a source if you wouldn't trust Erb views from them.
- The only truly Markdown-specific code in the source is
RDiscount.new(markdown_source).to_html
and the.md
/.markdown
file name extensions. This gem can and should be generalized into a general-purpose static template gem, so that you can easily use other static templating languages in Rails. Perhaps tilt will come in useful.