NimblePublisherMDEx

NimblePublisher adapter for MDEx and Lumis, with support for both static Markdown rendering and Phoenix LiveView rendering.

• Syntax highlighting for 110+ languages powered by Tree-sitter via Lumis
• 120+ color themes from the Neovim ecosystem
• Automatic light/dark mode
• Static Markdown to HTML rendering
• Phoenix HEEx support when :phoenix_live_view is installed
• Code block decorators
• GitHub Flavored Markdown via MDExGFM
• Extensible with more plugins — Mermaid diagrams, KaTeX math, Video, and more.

Getting Started

Pick the path that fits your situation:

• New project — start from scratch with Phoenix + blog
• Add a blog to an existing Phoenix project — scaffold a blog into your app
• Switch from Earmark to MDEx — already using NimblePublisher

New project

Install the Igniter archive if you haven't already:

mix archive.install hex igniter_new

Create a new Phoenix project with a blog already set up:

mix igniter.new my_blog --install nimble_publisher_mdex --with phx.new --with-args="--no-ecto"

This will generate a Phoenix app, add the dependency, and scaffold a blog module, sample post, and LiveView.

Add a blog to an existing Phoenix project

Run the installer to scaffold everything:

mix igniter.install nimble_publisher_mdex

This will add the dependency and generate a blog module, sample post, and LiveView. Then add the color-scheme meta tag to your root layout:

<meta name="color-scheme" content="light dark">

Switch from Earmark to MDEx

Add the dependency:

def deps do
  [
    {:nimble_publisher_mdex, "~> 0.1"}
  ]
end

Set the converter in your blog module:

use NimblePublisher,
  build: __MODULE__,
  from: "priv/posts/**/*.md",
  as: :posts,
  html_converter: NimblePublisherMDEx

Remove the :highlighters option and any makeup_* dependencies — MDEx handles syntax highlighting out of the box.

Add the color-scheme meta tag to your root layout:

<meta name="color-scheme" content="light dark">

Configuration

Pass :mdex_opts to customize MDEx Options

Built-in defaults include:

[
  plugins: [MDExGFM],
  extension: [phoenix_heex: true],
  render: [
    unsafe: true,
    github_pre_lang: true,
    full_info_string: true
  ],
  syntax_highlight: [
    engine: :lumis,
    opts: [
      formatter:
        {:html_multi_themes,
         themes: [light: "github_light", dark: "github_dark"], default_theme: "light-dark()"}
    ]
  ]
]

Static Markdown rendering works out of the box. If you also want MDEx to render Phoenix HEEx through LiveView, install the optional :phoenix_live_view dependency.

You can change the default options in the app config:

# config/config.exs
config :nimble_publisher_mdex,
  mdex_opts: [
    syntax_highlight: [
      engine: :lumis,
      opts: [formatter: {:html_inline, theme: "dracula"}]
    ]
  ]

Or pass options directly through NimblePublisher:

use NimblePublisher,
  build: __MODULE__,
  from: "priv/posts/**/*.md",
  as: :posts,
  html_converter: NimblePublisherMDEx,
  mdex_opts: [syntax_highlight: nil]

Themes

Browse all available themes at lumis.sh. Some popular choices:

License

MIT License. See LICENSE for details.