feat(pages, posts): use custom converter in frontmatter (#113)

Allow a page or post to specify a custom converter in the frontmatter.

The frontmatter key `:converter` is optional.  If included, it should
specify a string-value of a converter module.  If not included, the
default config setting will be used.

Closes #112

Author: andyl

lib/tableau/extensions/page_extension.ex

@@ -11,6 +11,7 @@ defmodule Tableau.PageExtension do
   * `:title` - The title of the page
   * `:permalink` - The permalink of the page.
   * `:layout` - A string representation of a Tableau layout module.
+  * `:converter` - A string representation of a converter module. (optional)
 
   ## Example
 
@@ -19,6 +20,7 @@ defmodule Tableau.PageExtension do
   title: "Getting Started"
   permalink: "/docs/:title"
   layout: "ElixirTools.PageLayout"
+  converter: "MyConverter"
   ```
 
   ## Permalink
@@ -59,6 +61,8 @@ defmodule Tableau.PageExtension do
       adoc: MySite.AsciiDocConverter
     ],
   ```
+
+  As noted above, a converter can be overridden on a specific page, using the frontmatter `:converter` key.
   """
 
   use Tableau.Extension, key: :pages, type: :pre_build, priority: 100
@@ -88,10 +92,11 @@ defmodule Tableau.PageExtension do
       config.dir
       |> Path.join("**/*.{#{exts}}")
       |> Common.paths()
-      |> Common.entries(fn %{path: path, ext: ext, front_matter: front_matter, pre_convert_body: pre_convert_body} ->
-        renderer = fn assigns -> converters[ext].convert(path, front_matter, pre_convert_body, assigns) end
-
-        {build(path, front_matter, pre_convert_body, config), renderer}
+      |> Common.entries(fn pathmap ->
+        {
+          build(pathmap.path, pathmap.front_matter, pathmap.pre_convert_body, config),
+          fn assigns -> pick_module_and_convert(converters, pathmap, assigns) end
+        }
       end)
 
     graph =
@@ -108,6 +113,14 @@ defmodule Tableau.PageExtension do
      |> Map.put(:graph, graph)}
   end
 
+  defp to_module(nil), do: nil
+  defp to_module(string) when is_binary(string), do: Module.concat(string, nil)
+
+  defp pick_module_and_convert(converters, pathmap, assigns) do
+    cnv_module = to_module(pathmap.front_matter[:converter]) || converters[pathmap.ext]
+    cnv_module.convert(pathmap.path, pathmap.front_matter, pathmap.pre_convert_body, assigns)
+  end
+
   defp build(filename, front_matter, body, pages_config) do
     front_matter
     |> Map.put(:__tableau_page_extension__, true)

lib/tableau/extensions/post_extension.ex

@@ -12,6 +12,7 @@ defmodule Tableau.PostExtension do
   * `:permalink` - The permalink of the post. `:title` will be replaced with the posts title and non alphanumeric characters removed. Optional.
   * `:date` - A string representation of an Elixir `NaiveDateTime`, often presented as a `sigil_N`. This will be converted to your configured timezone.
   * `:layout` - A string representation of a Tableau layout module.
+  * `:converter` - A string representation of a converter module. (optional)
 
   ## Example
 
@@ -21,6 +22,7 @@ defmodule Tableau.PostExtension do
   permalink: "/news/:title"
   date: "~N[2023-09-19 01:00:00]"
   layout: "ElixirTools.PostLayout"
+  converter: "MyConverter"
   ```
 
   ## Permalink
@@ -65,6 +67,8 @@ defmodule Tableau.PostExtension do
       adoc: MySite.AsciiDocConverter
     ],
   ```
+
+  As noted above, a converter can be overridden on a specific page, using the frontmatter `:converter` key.
   """
 
   use Tableau.Extension, key: :posts, type: :pre_build, priority: 100
@@ -96,10 +100,11 @@ defmodule Tableau.PostExtension do
       config.dir
       |> Path.join("**/*.{#{exts}}")
       |> Common.paths()
-      |> Common.entries(fn %{path: path, ext: ext, front_matter: front_matter, pre_convert_body: pre_convert_body} ->
-        renderer = fn assigns -> converters[ext].convert(path, front_matter, pre_convert_body, assigns) end
-
-        {build(path, front_matter, pre_convert_body, config), renderer}
+      |> Common.entries(fn pathmap ->
+        {
+          build(pathmap.path, pathmap.front_matter, pathmap.pre_convert_body, config),
+          fn assigns -> pick_module_and_convert(converters, pathmap, assigns) end
+        }
       end)
       |> Enum.sort_by(fn {post, _} -> post.date end, {:desc, DateTime})
       |> then(fn posts ->
@@ -124,6 +129,14 @@ defmodule Tableau.PostExtension do
      |> Map.put(:graph, graph)}
   end
 
+  defp to_module(nil), do: nil
+  defp to_module(string) when is_binary(string), do: Module.concat(string, nil)
+
+  defp pick_module_and_convert(converters, pathmap, assigns) do
+    cnv_module = to_module(pathmap.front_matter[:converter]) || converters[pathmap.ext]
+    cnv_module.convert(pathmap.path, pathmap.front_matter, pathmap.pre_convert_body, assigns)
+  end
+
   defp build(filename, attrs, body, posts_config) do
     Application.put_env(:date_time_parser, :include_zones_from, ~N[2010-01-01T00:00:00])
 

test/tableau/extensions/page_extension_test.exs

@@ -228,5 +228,34 @@ defmodule Tableau.PageExtensionTest do
                ]
              } = token
     end
+
+    test "renders with a custom converter in frontmatter", %{tmp_dir: dir, token: token} do
+      File.write(Path.join(dir, "a-page.md"), """
+      ---
+      title: missing layout key
+      type: articles
+      permalink: /:type/:title
+      converter: "Tableau.MDExConverter"
+      ---
+
+      A great page
+      """)
+
+      assert {:ok, token} = PageExtension.run(token)
+
+      assert %{
+               pages: [
+                 %{
+                   __tableau_page_extension__: true,
+                   body: "\nA great page\n",
+                   file: ^dir <> "/a-page.md",
+                   layout: Blog.DefaultPageLayout,
+                   permalink: "/articles/missing-layout-key",
+                   title: "missing layout key",
+                   type: "articles"
+                 }
+               ]
+             } = token
+    end
   end
 end

test/tableau/extensions/post_extension_test.exs

@@ -291,5 +291,37 @@ defmodule Tableau.PostExtensionTest do
                ]
              } = token
     end
+
+    test "renders with a custom converter in frontmatter", %{tmp_dir: dir, token: token} do
+      File.write(Path.join(dir, "a-post.md"), """
+      ---
+      title: foo man chu_foo.js
+      type: articles
+      layout: Some.Layout
+      date: 2023-02-01 00:01:00
+      permalink: /:type/:year/:month/:day/:title
+      converter: "Tableau.MDExConverter"
+      ---
+
+      A great post
+      """)
+
+      assert {:ok, token} = PostExtension.run(token)
+
+      assert %{
+               posts: [
+                 %{
+                   __tableau_post_extension__: true,
+                   body: "\nA great post\n",
+                   date: ~U[2023-02-01 00:01:00Z],
+                   file: ^dir <> "/a-post.md",
+                   layout: Some.Layout,
+                   permalink: "/articles/2023/02/01/foo-man-chu-foo.js",
+                   title: "foo man chu_foo.js",
+                   type: "articles"
+                 }
+               ]
+             } = token
+    end
   end
 end