PhoenixMarkdown

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

Read the original blog post.

Powered by Padmark

---

Usage

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

def deps do
  [
    {:phoenix_markdown, "~> 1.0"}
  ]
end

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

3. Use the .html.md extensions for your templates.

---

Optional Live Reload Configuration

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:

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 Padmark Configuration

You can configure phoenix_markdown via two separate configuration blocks.

The first one is the options passed to Padmark.as_html!/2 as it renders markdown into HTML:

config :phoenix_markdown, :padmark,
  gfm_tables: true,
  breaks: true

Please read the Padmark.Options documentation to understand all available options (GFM tables, footnotes, subscript/superscript, hard line breaks, HTML escaping, and more).

The Padmark options set here apply to all .md template files.

---

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 via Padmark. The default is to escape.

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 useful to 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 flag.
• :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/**".
  • A regex against the path: ~r/.+%%.+/.

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"]

---

Generators

There are no generators for phoenix_markdown since templates are authored directly in Markdown. You can embed server-side tags if you turn them on in configuration, or keep them static and reference them from regular views and templates:

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

Markdown is intended to be written by a human in any text editor. Just create a file with the .html.md extension in the appropriate templates folder in your Phoenix application, and use it like any other template.

---

Quality & Compliance

PhoenixMarkdown is fully tested, typed, and documented:

• 100% Doctor documentation & spec coverage
• Zero Dialyzer warnings
• Strict Credo style checks
• 100% test coverage
• Zero vulnerable dependencies (mix hex.audit / mix audit)

To run the complete check suite locally:

mix check

---

License

MIT License. Copyright (c) 2016 Boyd Multerer, 2024-2026 Altenwald Solutions, S.L.