feat: PageExtension

The page extension allows you to create arbitrary pages with documents
like markdown.

Author: mhanberg

lib/tableau/extensions/page_extension.ex

@@ -0,0 +1,102 @@
+defmodule Tableau.PageExtension do
+  @moduledoc """
+  Markdown files (with YAML frontmatter) in the configured pages directory will be automatically compiled into Tableau pages.
+
+  Certain frontmatter keys are required and all keys are passed as options to the `Tableau.Page`.
+
+  ## Options
+
+  Frontmatter is compiled with `yaml_elixir` and all keys are converted to atoms.
+
+  * `:id` - An Elixir module to be used when compiling the backing `Tableau.Page`. A leaking implementation detail that should be fixed eventually.
+  * `:title` - The title of the page
+  * `:permalink` - The permalink of the page.
+  * `:layout` - A string representation of a Tableau layout module.
+
+  ## Example
+
+  ```yaml
+  id: "GettingStarted"
+  title: "Getting Started"
+  permalink: "/docs/:title"
+  layout: "ElixirTools.PageLayout"
+  ```
+
+  ## Permalink
+
+  The permalink is a string with colon prefixed template variables.
+
+  These variables will be swapped with the corresponding YAML Frontmatter key, with the result being piped through `to_string/1`.
+
+  ## Configuration
+
+  - `:enabled` - boolean - Extension is active or not.
+  - `:dir` - string - Directory to scan for markdown files. Defaults to `_pages`
+  - `:permalink` - string - Default output path for pages. Accepts `:title` as a replacement keyword, replaced with the page's provided title. If a page has a `:permalink` provided, that will override this value _for that page_.
+  - `:layout` - string - Elixir module providing page layout for pages. Default is nil.
+
+  ### Example
+
+  ```elixir
+  config :tableau, Tableau.PageExtension,
+    enabled: true,
+    dir: "_docs",
+    permalink: "/docs/:title",
+    layout: "MyApp.PageLayout"
+  ```
+  """
+
+  use Tableau.Extension, key: :pages, type: :pre_build, priority: 100
+
+  {:ok, config} =
+    Tableau.PageExtension.Config.new(Map.new(Application.compile_env(:tableau, Tableau.PageExtension, %{})))
+
+  @config config
+
+  def run(token) do
+    :global.trans(
+      {:create_pages_module, make_ref()},
+      fn ->
+        Module.create(
+          Tableau.PageExtension.Pages,
+          quote do
+            use NimblePublisher,
+              build: __MODULE__.Page,
+              from: "#{unquote(@config.dir)}/**/*.md",
+              as: :pages,
+              parser: Tableau.PageExtension.Pages.Page,
+              html_converter: Tableau.PageExtension.Pages.HTMLConverter
+
+            def pages(_opts \\ []) do
+              @pages
+            end
+          end,
+          Macro.Env.location(__ENV__)
+        )
+
+        pages =
+          for page <- apply(Tableau.PageExtension.Pages, :pages, []) do
+            {:module, _module, _binary, _term} =
+              Module.create(
+                Module.concat([page.id]),
+                quote do
+                  use Tableau.Page, unquote(Macro.escape(Keyword.new(page)))
+
+                  @external_resource unquote(page.file)
+                  def template(_assigns) do
+                    unquote(page.body)
+                  end
+                end,
+                Macro.Env.location(__ENV__)
+              )
+
+            page
+          end
+
+        {:ok, Map.put(token, :pages, pages)}
+      end,
+      [Node.self()],
+      :infinity
+    )
+  end
+end

lib/tableau/extensions/page_extension/config.ex

@@ -0,0 +1,22 @@
+defmodule Tableau.PageExtension.Config do
+  @moduledoc false
+
+  import Schematic
+
+  defstruct enabled: true, dir: "_pages", permalink: nil, layout: nil
+
+  def new(input), do: unify(schematic(), input)
+
+  def schematic do
+    schema(
+      __MODULE__,
+      %{
+        optional(:enabled) => bool(),
+        optional(:dir) => str(),
+        optional(:permalink) => str(),
+        optional(:layout) => str()
+      },
+      convert: false
+    )
+  end
+end

lib/tableau/extensions/page_extension/pages/html_converter.ex

@@ -0,0 +1,8 @@
+defmodule Tableau.PageExtension.Pages.HTMLConverter do
+  @moduledoc false
+  def convert(_filepath, body, _attrs, _opts) do
+    {:ok, config} = Tableau.Config.new(Map.new(Application.get_env(:tableau, :config, %{})))
+
+    MDEx.to_html(body, config.markdown[:mdex])
+  end
+end

lib/tableau/extensions/page_extension/pages/page.ex

@@ -0,0 +1,47 @@
+defmodule Tableau.PageExtension.Pages.Page do
+  @moduledoc false
+  def build(filename, attrs, body) do
+    {:ok, page_config} =
+      Tableau.PageExtension.Config.new(Map.new(Application.get_env(:tableau, Tableau.PageExtension, %{})))
+
+    attrs
+    |> Map.put(:body, body)
+    |> Map.put(:file, filename)
+    |> Map.put(:layout, Module.concat([attrs.layout || page_config.layout]))
+    |> build_permalink(page_config)
+  end
+
+  def parse(_file_path, content) do
+    Tableau.YamlFrontMatter.parse!(content, atoms: true)
+  end
+
+  defp build_permalink(%{permalink: permalink} = attrs, _config) do
+    permalink
+    |> transform_permalink(attrs)
+    |> then(&Map.put(attrs, :permalink, &1))
+  end
+
+  defp build_permalink(attrs, %{permalink: permalink}) when not is_nil(permalink) do
+    permalink
+    |> transform_permalink(attrs)
+    |> then(&Map.put(attrs, :permalink, &1))
+  end
+
+  defp build_permalink(%{file: filename} = attrs, config) do
+    filename
+    |> Path.rootname()
+    |> String.replace_prefix(config.dir, "")
+    |> transform_permalink(attrs)
+    |> then(&Map.put(attrs, :permalink, &1))
+  end
+
+  defp transform_permalink(path, attrs) do
+    vars = Map.new(attrs, fn {k, v} -> {":#{k}", v} end)
+
+    path
+    |> String.replace(Map.keys(vars), &to_string(Map.fetch!(vars, &1)))
+    |> String.replace(" ", "-")
+    |> String.replace(~r/[^[:alnum:]\/\-]/, "")
+    |> String.downcase()
+  end
+end