Enable new markdown options (#591)

* Enable new markdown options

- Add new mdex options
- Bump min mdex version
- Add guide to customize such options

CHANGELOG.md

@@ -6,12 +6,18 @@
   * Require minimum Elixir v1.14
 
 ### Enhancements
+  * Enable Markdown options: `:footnotes`, `:multiline_block_quotes`, `:shortcodes` (emojis), `:underline`, `:escape`, `:relaxed_tasklist_matching`, and `:relaxed_autolinks`.
+    See https://docs.rs/comrak/latest/comrak/struct.ExtensionOptions.html and https://docs.rs/comrak/latest/comrak/struct.ParseOptions.html for more info.
   * Added Shared Info Handlers (`info_handle` callbacks) - [#578](https://github.com/BeaconCMS/beacon/pull/578) by [@ddink](https://github.com/ddink)
 
 ### Fixes
   * [Heroicons] Namespace the vendorized module as `Beacon.Heroicons` to avoid conflicts
 
+### Breaking Changes
+  * Require minimun `:mdex` v0.1.17
+
 ### Documentation
+  * Added guide to customize the Markdown options
   * Added guide on how to embed tweets using the Twitter JS api
 
 ## 0.1.0-rc.2 (2024-09-20)

guides/recipes/customize-markdown-rendering.md

@@ -0,0 +1,34 @@
+# Customize Markdown Rendering
+
+Markdown pages are rendered using the [Beacon.Template.Markdown](https://hexdocs.pm/beacon/0.1.0-rc.2/Beacon.Template.Markdown.html) module with a set of default options that works for most cases,
+but you might want to change how some features work or enable more features. For example, let's suppose you want to generate an ID for every header of the page with the suffix `"topic-"`.
+
+You can do that by changing the `:load_template` lifecycle of `:markdown` in your [site configuration](https://hexdocs.pm/beacon/0.1.0-rc.2/Beacon.html#start_link/1) as the example below:
+
+```elixir
+[
+  site: :my_site,
+  lifecycle: [
+    load_template: [
+      {:markdown,
+        [
+          markdown_with_header_ids: &markdown_with_header_ids/2
+        ]
+      }
+    ]
+  ]
+  # rest ommited for brevity...
+]
+
+def markdown_with_header_ids(template, _metadata) do
+  template = MDEx.to_html!(markdown, extension: [header_ids: "topic-"])
+  {:cont, template}
+end
+```
+
+But keep in mind this operation will replace the default markdown rendering with the one you provided,
+so the only features enabled will be the one you set and the others will take the default value.
+
+For example with this configuration the `:header_ids` extension is enabled but others like tables and autolinks would be turned off.
+
+You can inspect the actual configuration in the [Beacon.Template.Markdown](https://hexdocs.pm/beacon/0.1.0-rc.2/Beacon.Template.Markdown.html) module and also check the [MDEx docs](https://hexdocs.pm/mdex/MDEx.html#to_html/2) for more info.

lib/beacon/template/markdown.ex

@@ -28,12 +28,19 @@ defmodule Beacon.Template.Markdown do
           autolink: true,
           tasklist: true,
           superscript: true,
-          description_lists: true
+          footnotes: true,
+          description_lists: true,
+          multiline_block_quotes: true,
+          shortcodes: true,
+          underline: true
         ],
         parse: [smart: true],
         render: [
           hardbreaks: false,
-          unsafe_: true
+          unsafe_: true,
+          escape: true,
+          relaxed_tasklist_matching: true,
+          relaxed_autolinks: true
         ],
         features: [
           syntax_highlight_theme: syntax_highlight_theme

mix.exs

@@ -55,7 +55,7 @@ defmodule Beacon.MixProject do
       override_dep(:phoenix, "~> 1.7", "PHOENIX_VERSION", "PHOENIX_PATH"),
       override_dep(:phoenix_live_view, "~> 0.20", "PHOENIX_LIVE_VIEW_VERSION", "PHOENIX_LIVE_VIEW_PATH"),
       override_dep(:live_monaco_editor, "~> 0.1", "LIVE_MONACO_EDITOR_VERSION", "LIVE_MONACO_EDITOR_PATH"),
-      override_dep(:mdex, "~> 0.1", "MDEX_VERSION", "MDEX_PATH"),
+      override_dep(:mdex, "~> 0.1.17", "MDEX_VERSION", "MDEX_PATH"),
 
       # Runtime
       {:accent, "~> 1.1"},

mix.lock

@@ -2,7 +2,7 @@
   "accent": {:hex, :accent, "1.1.1", "20257356446d45078b19b91608f74669b407b39af891ee3db9ee6824d1cae19d", [:mix], [{:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: true]}, {:plug, "~> 1.3", [hex: :plug, repo: "hexpm", optional: false]}], "hexpm", "6d5afa50d4886e3370e04fa501468cbaa6c4b5fe926f72ccfa844ad9e259adae"},
   "bunt": {:hex, :bunt, "1.0.0", "081c2c665f086849e6d57900292b3a161727ab40431219529f13c4ddcf3e7a44", [:mix], [], "hexpm", "dc5f86aa08a5f6fa6b8096f0735c4e76d54ae5c9fa2c143e5a1fc7c1cd9bb6b5"},
   "bypass": {:hex, :bypass, "2.1.0", "909782781bf8e20ee86a9cabde36b259d44af8b9f38756173e8f5e2e1fabb9b1", [:mix], [{:plug, "~> 1.7", [hex: :plug, repo: "hexpm", optional: false]}, {:plug_cowboy, "~> 2.0", [hex: :plug_cowboy, repo: "hexpm", optional: false]}, {:ranch, "~> 1.3", [hex: :ranch, repo: "hexpm", optional: false]}], "hexpm", "d9b5df8fa5b7a6efa08384e9bbecfe4ce61c77d28a4282f79e02f1ef78d96b80"},
-  "castore": {:hex, :castore, "1.0.8", "dedcf20ea746694647f883590b82d9e96014057aff1d44d03ec90f36a5c0dc6e", [:mix], [], "hexpm", "0b2b66d2ee742cb1d9cb8c8be3b43c3a70ee8651f37b75a8b982e036752983f1"},
+  "castore": {:hex, :castore, "1.0.9", "5cc77474afadf02c7c017823f460a17daa7908e991b0cc917febc90e466a375c", [:mix], [], "hexpm", "5ea956504f1ba6f2b4eb707061d8e17870de2bee95fb59d512872c2ef06925e7"},
   "cc_precompiler": {:hex, :cc_precompiler, "0.1.10", "47c9c08d8869cf09b41da36538f62bc1abd3e19e41701c2cea2675b53c704258", [:mix], [{:elixir_make, "~> 0.7", [hex: :elixir_make, repo: "hexpm", optional: false]}], "hexpm", "f6e046254e53cd6b41c6bacd70ae728011aa82b2742a80d6e2214855c6e06b22"},
   "certifi": {:hex, :certifi, "2.12.0", "2d1cca2ec95f59643862af91f001478c9863c2ac9cb6e2f89780bfd8de987329", [:rebar3], [], "hexpm", "ee68d85df22e554040cdb4be100f33873ac6051387baf6a8f6ce82272340ff1c"},
   "cowboy": {:hex, :cowboy, "2.12.0", "f276d521a1ff88b2b9b4c54d0e753da6c66dd7be6c9fca3d9418b561828a3731", [:make, :rebar3], [{:cowlib, "2.13.0", [hex: :cowlib, repo: "hexpm", optional: false]}, {:ranch, "1.8.0", [hex: :ranch, repo: "hexpm", optional: false]}], "hexpm", "8a7abe6d183372ceb21caa2709bec928ab2b72e18a3911aa1771639bef82651e"},
@@ -56,7 +56,7 @@
   "poison": {:hex, :poison, "6.0.0", "9bbe86722355e36ffb62c51a552719534257ba53f3271dacd20fbbd6621a583a", [:mix], [{:decimal, "~> 2.1", [hex: :decimal, repo: "hexpm", optional: true]}], "hexpm", "bb9064632b94775a3964642d6a78281c07b7be1319e0016e1643790704e739a2"},
   "postgrex": {:hex, :postgrex, "0.19.1", "73b498508b69aded53907fe48a1fee811be34cc720e69ef4ccd568c8715495ea", [:mix], [{:db_connection, "~> 2.1", [hex: :db_connection, repo: "hexpm", optional: false]}, {:decimal, "~> 1.5 or ~> 2.0", [hex: :decimal, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: true]}, {:table, "~> 0.1.0", [hex: :table, repo: "hexpm", optional: true]}], "hexpm", "8bac7885a18f381e091ec6caf41bda7bb8c77912bb0e9285212829afe5d8a8f8"},
   "ranch": {:hex, :ranch, "1.8.0", "8c7a100a139fd57f17327b6413e4167ac559fbc04ca7448e9be9057311597a1d", [:make, :rebar3], [], "hexpm", "49fbcfd3682fab1f5d109351b61257676da1a2fdbe295904176d5e521a2ddfe5"},
-  "rustler_precompiled": {:hex, :rustler_precompiled, "0.7.2", "097f657e401f02e7bc1cab808cfc6abdc1f7b9dc5e5adee46bf2fd8fdcce9ecf", [:mix], [{:castore, "~> 0.1 or ~> 1.0", [hex: :castore, repo: "hexpm", optional: false]}, {:rustler, "~> 0.23", [hex: :rustler, repo: "hexpm", optional: true]}], "hexpm", "7663faaeadc9e93e605164dcf9e69168e35f2f8b7f2b9eb4e400d1a8e0fe2999"},
+  "rustler_precompiled": {:hex, :rustler_precompiled, "0.8.1", "8afe0b6f3a9a677ada046cdd23e3f4c6399618b91a6122289324774961281e1e", [:mix], [{:castore, "~> 0.1 or ~> 1.0", [hex: :castore, repo: "hexpm", optional: false]}, {:rustler, "~> 0.23", [hex: :rustler, repo: "hexpm", optional: true]}], "hexpm", "90b8c2297bf7959cfa1c927b2881faad7bb0707183124955369991b76177a166"},
   "safe_code": {:hex, :safe_code, "0.2.3", "c37329a03d4ac847ccd437344abdbb6d8a8ff6a46f1b6e5ad976bf9a86a5227f", [:mix], [{:jason, "~> 1.3", [hex: :jason, repo: "hexpm", optional: false]}, {:phoenix_live_view, ">= 0.18.17", [hex: :phoenix_live_view, repo: "hexpm", optional: false]}], "hexpm", "de5f3ad37d0f7804281f42be8dac32ee52f7b5f7c5c4c851eba34e42bffd4aef"},
   "solid": {:hex, :solid, "0.15.2", "6921af98a3a862041bb6af72b5f6e094dbf0242366b142f98a92cabe4ed30d2a", [:mix], [{:nimble_parsec, "~> 1.0", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "18b062b04948b7f7b99ac4a9360681dac7e0bd142df5e62a7761696c7384be45"},
   "ssl_verify_fun": {:hex, :ssl_verify_fun, "1.1.7", "354c321cf377240c7b8716899e182ce4890c5938111a1296add3ec74cf1715df", [:make, :mix, :rebar3], [], "hexpm", "fe4c190e8f37401d30167c8c405eda19469f34577987c76dde613e838bbc67f8"},