Phoenix Template Engine for Markdown
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
config
lib
test
.gitignore
.travis.yml
LICENSE
README.md
changelist.md
mix.exs
mix.lock

README.md

Markdown Template Engine for Phoenix

Build Status Hex.pm Inline docs Hex.pm Hex.pm

A Markdown template engine for Phoenix. It also lets you (optionally) embed EEx tags to be evaulated on the server.

Read the blog post.

Powered by Earmark

Usage

  1. Add {:phoenix_markdown, "~> 1.0"} to your deps in mix.exs.
  2. Add the following to your Phoenix config/config.exs
  config :phoenix, :template_engines,
    md: PhoenixMarkdown.Engine

If you are also using the phoenix_haml engine, then it should look like this:

  config :phoenix, :template_engines,
    haml: PhoenixHaml.Engine,
    md:   PhoenixMarkdown.Engine
  1. Use the .html.md extensions for your templates.

Optional

Add md extension to Phoenix live reload in config/dev.exs

  config :hello_phoenix, HelloPhoenix.Endpoint,
    live_reload: [
      patterns: [
        ~r{priv/static/.*(js|css|png|jpeg|jpg|gif|svg)$},
        ~r{web/views/.*(ex)$},
        ~r{web/templates/.*(eex|md)$}
      ]
    ]

If you are also using the phoenix_haml engine, then the pattern should look like this:

  config :hello_phoenix, HelloPhoenix.Endpoint,
    live_reload: [
      patterns: [
        ~r{priv/static/.*(js|css|png|jpeg|jpg|gif|svg)$},
        ~r{web/views/.*(ex)$},
        ~r{web/templates/.*(eex|haml|md)$}
      ]
    ]

Optional Earmark Configuration

You can configure phoenix_markdown via two seperate configuration blocks.

The first one is, literally, the options that will be passed to Earmark as it renders the markdown into html.

  config :phoenix_markdown, :earmark, %{
    gfm: true,
    breaks: true
  }

Please read the Earmark Documentation to understand the options that can go here.

The Earmark options set here apply to all .md template files. If anybody has a good idea on how to pass per-file options to a template complier, I'm open to suggestions.

Optional Server Tags Configuration

The second configuration block is where you indicate if you want to evaluate EEx tags on the server or escape them Earmark. The default is to escape in Earmark.

Example of markdown content with a server-side tag:

  ## Before server-side content

  <%= 11 + 2 %>

  After the server-side content

To turn on server-side eex tags, set the :server_tags configuration option.

  config :phoenix_markdown, :server_tags, :all

The options to turn on server tags are :all, :only and :except. Anything else (or not setting it at all) leaves the tags escaped in Markdown.

  • :all evaluates all server tags in all markdown files.
  • :only Only files that match the pattern or patterns will be evaluated. This pattern can be any of:
    • The name of the final html file: "sample.html"
    • The full path of the template file: "lib/sample_web/templates/page/sample.html.md"
    • A path with wildcards: "**/page/**". This is nice as it would evaluate all files in a single directory.
    • A regex against the path: ~r/.+%%.+/. This allows you to use a character sequence in the name as a per-file (or path) flag saying if it should be evaluated.
  • :except Only files that do NOT match the pattern or patterns will be evaluated. This pattern can be any of:
    • The name of the final html file: "sample.html"
    • The full path of the template file: "lib/sample_web/templates/page/sample.html.md"
    • A path with wildcards: "**/page/**". This is nice as it would prevent evaluation of all files in a single directory.
    • A regex against the path: ~r/.+%%.+/. This allows you to use a character sequence in the name as a per-file (or path) flag saying if it not should be evaluated.

Both the :only and :except options accept either a single pattern, or a list of patterns.

  config :phoenix_markdown, :server_tags, only: ~r/.+%%.+/

or...

  config :phoenix_markdown, :server_tags, only: [~r/.+%%.+/, "some_file.html"]

Unexpected Token in Server Tags

By default Earmark replaces some characters with prettier UTF-8 versions. For example, single and double quotes are replaced with left- and right-handed versions. This may break any server tag which contains a prettified character since EEx cannot interpret them as intended. To fix this, disable smartypants processing.

  config :phoenix_markdown, :earmark, %{
    smartypants: false
  }

Generators

There are no generators for phoenix_markdown since they wouldn't make sense. You can embed server-side tags if you turn them on in the configuration, but otherwise just keep it static and refer to it from an eex template.

Like this:

  <% render("some_markdown.html") %>

Markdown is intended to be written by a human in any simple text editor ( or a fancy one like iA Writer ). Just create a file with the .html.md extension and drop it into the appropriate templates folder in your phoenix application. Then you can use it just like any other template.