feat: add optional config/1 callback to extensions (#104)

This callback can be used for an extension to validate its configuration
in a way that can provide better errors for the user

refactor: extract common elements from extensions

refactor: reduce unnecessary code

refactor: pass in configuration to extensions from the build task

test: add tests for post and page extensions

Author: mhanberg

.github/workflows/ci.yaml

@@ -12,12 +12,10 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        elixir: [1.15.x, 1.16.x, 1.17.x]
+        elixir: [1.16.x, 1.17.x]
         otp: [25.x, 26.x]
 
         include:
-          - elixir: 1.15.x
-            otp: 24.x
           - elixir: 1.17.x
             otp: 27.x
 

lib/mix/tasks/tableau.build.ex

@@ -25,6 +25,9 @@ defmodule Mix.Tasks.Tableau.Build do
       |> Stream.map(fn {:ok, mod} -> mod end)
       |> Enum.to_list()
 
+    {:ok, config} = Tableau.Config.get()
+    token = Map.put(token, :extensions, %{})
+
     token = mods |> extensions_for(:pre_build) |> run_extensions(token)
 
     graph = Tableau.Graph.insert(token.graph, mods)
@@ -61,9 +64,9 @@ defmodule Mix.Tasks.Tableau.Build do
     token
   end
 
-  defp validate_config(config_mod, raw_config) do
-    if Code.ensure_loaded?(config_mod) do
-      config_mod.new(raw_config)
+  defp validate_config(module, raw_config) do
+    if function_exported?(module, :config, 1) do
+      module.config(raw_config)
     else
       {:ok, raw_config}
     end
@@ -81,17 +84,15 @@ defmodule Mix.Tasks.Tableau.Build do
   defp run_extensions(extensions, token) do
     for module <- extensions, reduce: token do
       token ->
-        config_mod = Module.concat([module, Config])
-
         raw_config =
           :tableau |> Application.get_env(module, %{enabled: true}) |> Map.new()
 
         if raw_config[:enabled] do
-          {:ok, config} = validate_config(config_mod, raw_config)
+          {:ok, config} = validate_config(module, raw_config)
 
           {:ok, key} = Tableau.Extension.key(module)
 
-          token = put_in(token[key], config)
+          token = put_in(token.extensions[key], %{config: config})
 
           case module.run(token) do
             {:ok, token} ->

lib/tableau/config.ex

@@ -21,10 +21,6 @@ defmodule Tableau.Config do
     Tableau.Config.new(Map.new(Application.get_env(:tableau, :config, %{})))
   end
 
-  defp atom do
-    raw(&is_atom/1, message: "expected an atom")
-  end
-
   defp keyword(value) do
     list(tuple([atom(), value]))
   end

lib/tableau/converters/mdex_converter.ex

@@ -2,9 +2,7 @@ defmodule Tableau.MDExConverter do
   @moduledoc """
   Converter to parse markdown content with `MDEx`
   """
-  def convert(_filepath, _front_matter, body, _opts) do
-    {:ok, config} = Tableau.Config.get()
-
+  def convert(_filepath, _front_matter, body, %{config: config}) do
     MDEx.to_html!(body, config.markdown[:mdex])
   end
 end

lib/tableau/extension.ex

@@ -67,6 +67,16 @@ defmodule Tableau.Extension do
   """
   @callback run(token()) :: {:ok, token()} | :error
 
+  @doc """
+  Optional callback to validate the config for an extension. Useful for 
+  providing more useful error messages for misconfigurations.
+  """
+  @callback config(Keyword.t() | map()) :: {:ok, map()} | {:error, any()}
+
+  @optional_callbacks [
+    config: 1
+  ]
+
   defmacro __using__(opts) do
     opts = Keyword.validate!(opts, [:key, :enabled, :type, :priority])
 

lib/tableau/extensions/common.ex

@@ -1,15 +1,78 @@
 defmodule Tableau.Extension.Common do
   @moduledoc false
 
+  @doc """
+  Expand content paths from a wildcard.
+  """
   def paths(wildcard) do
     wildcard |> Path.wildcard() |> Enum.sort()
   end
 
+  @doc """
+  Build content entries from a list of paths.
+
+  Content should contain YAML frontmatter, with the body from the file passed to the callback.
+  """
   def entries(paths, callback) do
     for path <- paths do
       {front_matter, body} = Tableau.YamlFrontMatter.parse!(File.read!(path), atoms: true)
       "." <> ext = Path.extname(path)
       callback.(%{path: path, ext: String.to_atom(ext), front_matter: front_matter, pre_convert_body: body})
     end
   end
+
+  @doc """
+  Builds a permalink from a template and frontmatter and/or config.
+
+  Frontmatter keys are substituted for colon prefixed template keys of the same name.
+
+  If no permalink template is provided, the permalink will be derived from the file path.
+
+  If the frontamtter contains a `:date` key, it is broken down into `:day`, `:month`, and `:year`
+  components and those can be used in the permalink template.
+  """
+  def build_permalink(%{permalink: permalink} = front_matter, _config) do
+    permalink
+    |> transform_permalink(front_matter)
+    |> then(&Map.put(front_matter, :permalink, &1))
+  end
+
+  def build_permalink(front_matter, %{permalink: permalink}) when not is_nil(permalink) do
+    permalink
+    |> transform_permalink(front_matter)
+    |> then(&Map.put(front_matter, :permalink, &1))
+  end
+
+  def build_permalink(%{file: filename} = front_matter, config) do
+    filename
+    |> Path.rootname()
+    |> String.replace_prefix(config.dir, "")
+    |> transform_permalink(front_matter)
+    |> then(&Map.put(front_matter, :permalink, &1))
+  end
+
+  defp transform_permalink(path, front_matter) do
+    vars =
+      front_matter
+      |> Map.new(fn {k, v} -> {":#{k}", v} end)
+      |> then(fn vars ->
+        if is_struct(front_matter[:date], DateTime) do
+          Map.merge(vars, %{
+            ":day" => front_matter.date.day |> to_string() |> String.pad_leading(2, "0"),
+            ":month" => front_matter.date.month |> to_string() |> String.pad_leading(2, "0"),
+            ":year" => front_matter.date.year
+          })
+        else
+          vars
+        end
+      end)
+
+    path
+    |> String.replace(Map.keys(vars), &to_string(Map.fetch!(vars, &1)))
+    |> String.replace(" ", "-")
+    |> String.replace("_", "-")
+    |> String.replace(~r/[^[:alnum:]\/\-.]/, "")
+    |> String.downcase()
+    |> URI.encode()
+  end
 end

lib/tableau/extensions/data_extension.ex

@@ -57,9 +57,21 @@ defmodule Tableau.DataExtension do
   """
   use Tableau.Extension, key: :data, type: :pre_build, priority: 200
 
+  import Schematic
+
+  def config(config) do
+    unify(
+      map(%{
+        optional(:enabled, true) => bool(),
+        optional(:dir, "_data") => str()
+      }),
+      config
+    )
+  end
+
   def run(token) do
     data =
-      for file <- Path.wildcard(Path.join(token.data.dir, "**/*.{yml,yaml,exs}")), into: %{} do
+      for file <- Path.wildcard(Path.join(token.extensions.data.config.dir, "**/*.{yml,yaml,exs}")), into: %{} do
         case Path.extname(file) do
           ".exs" ->
             key = Path.basename(file, ".exs")

lib/tableau/extensions/data_extension/config.ex

@@ -63,15 +63,24 @@ defmodule Tableau.PageExtension do
 
   use Tableau.Extension, key: :pages, type: :pre_build, priority: 100
 
+  import Schematic
+
   alias Tableau.Extension.Common
-  alias Tableau.PageExtension.Page
 
-  @config Map.new(Application.compile_env(:tableau, Tableau.PageExtension, %{}))
+  def config(input) do
+    unify(
+      map(%{
+        optional(:enabled, true) => bool(),
+        optional(:dir, "_pages") => str(),
+        optional(:permalink) => str(),
+        optional(:layout) => str()
+      }),
+      input
+    )
+  end
 
   def run(token) do
-    {:ok, config} = Tableau.PageExtension.Config.new(@config)
-
-    {:ok, %{converters: converters}} = Tableau.Config.get()
+    %{site: %{config: %{converters: converters}}, extensions: %{pages: %{config: config}}} = token
 
     exts = Enum.map_join(converters, ",", fn {ext, _} -> to_string(ext) end)
 
@@ -82,7 +91,7 @@ defmodule Tableau.PageExtension do
       |> 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
 
-        {Page.build(path, front_matter, pre_convert_body), renderer}
+        {build(path, front_matter, pre_convert_body, config), renderer}
       end)
 
     graph =
@@ -98,4 +107,13 @@ defmodule Tableau.PageExtension do
      |> Map.put(:pages, pages |> Enum.unzip() |> elem(0))
      |> Map.put(:graph, graph)}
   end
+
+  defp build(filename, front_matter, body, pages_config) do
+    front_matter
+    |> Map.put(:__tableau_page_extension__, true)
+    |> Map.put(:body, body)
+    |> Map.put(:file, filename)
+    |> Map.put(:layout, Module.concat([front_matter.layout || pages_config.layout]))
+    |> Common.build_permalink(pages_config)
+  end
 end