Markdown Template Engine for Phoenix

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

Powered by Earmark

Usage

Add {:phoenix_markdown, "~> 1.0"} to your deps in mix.exs.

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

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.

boydm / phoenix_markdown

readme