s/path/permalink, add docs

Author: paradox460

lib/tableau/extensions/post_extension.ex

@@ -1,7 +1,18 @@
 defmodule Tableau.PostExtension.Config do
+  @moduledoc """
+  Configuration for PostExtension.
+
+  ## Options
+    - `:enabled` - boolean - Extension is active or not.
+    - `:dir` - string - Directory to scan for markdown files. Defaults to `_posts`
+    - `:future` - boolean - Show posts that have dates later than the current timestamp, or time at which the site is generated.
+    - `:permalink` - string - Default output path for posts. Accepts `:slug` as a replacement keyword, replaced with the post's provided slug.
+    - `layout` - string - Elixir module providing page layout for posts. Default is nil
+  """
+
   import Schematic
 
-  defstruct enabled: true, dir: "_posts", future: false, path: "/posts/:slug", layout: nil
+  defstruct enabled: true, dir: "_posts", future: false, permalink: "/posts/:slug", layout: nil
 
   def new(input), do: unify(schematic(), input)
 
@@ -11,8 +22,8 @@ defmodule Tableau.PostExtension.Config do
       %{
         optional(:enabled) => bool(),
         optional(:dir) => str(),
-        optional(:path) => str(),
         optional(:future) => bool(),
+        optional(:permalink) => str(),
         optional(:layout) => str()
       },
       convert: false
@@ -49,24 +60,24 @@ defmodule Tableau.PostExtension.Posts.Post do
 
   defp build_permalink(%{permalink: permalink} = attrs, _config) do
     permalink
-    |> transform_path(attrs)
+    |> transform_permalink(attrs)
     |> then(&Map.put(attrs, :permalink, &1))
   end
 
-  defp build_permalink(%{slug: slug} = attrs, %{path: path}) do
+  defp build_permalink(%{slug: slug} = attrs, %{permalink: permalink}) do
     slug
-    |> transform_path(attrs)
-    |> then(&Map.put(attrs, :permalink, String.replace(path, :slug, &1)))
+    |> transform_permalink(attrs)
+    |> then(&Map.put(attrs, :permalink, String.replace(permalink, :slug, &1)))
   end
 
-  defp build_permalink(%{file: filename} = attrs, %{path: path}) do
+  defp build_permalink(%{file: filename} = attrs, %{permalink: permalink}) do
     filename
     |> Path.basename(".md")
-    |> transform_path(attrs)
-    |> then(&Map.put(attrs, :permalink, String.replace(path, ":slug", &1)))
+    |> transform_permalink(attrs)
+    |> then(&Map.put(attrs, :permalink, String.replace(permalink, ":slug", &1)))
   end
 
-  defp transform_path(path, attrs) do
+  defp transform_permalink(path, attrs) do
     path
     |> String.replace(":title", attrs.title)
     |> String.replace(" ", "-")
@@ -87,8 +98,8 @@ defmodule Tableau.PostExtension do
 
   * `:id` - An Elixir module to be used when compiling the backing `Tableau.Page`
   * `:title` - The title of the post
-  * `:permalink` - The permalink of the post. `:title` will be replaced with the posts title and non alphanumeric characters removed
-  * `:slug` - A URL slug of the post. Only used if `:permalink` is unset
+  * `:permalink` - The permalink of the post. `:title` will be replaced with the posts title and non alphanumeric characters removed. Optional.
+  * `:slug` - A URL slug of the post. Only used if `:permalink` is unset. `:title` will be replaced with the posts title. Optional
   * `:date` - An Elixir `NaiveDateTime`, often presented as a `sigil_N`
   * `:layout` - A Tableau layout module.
 
@@ -103,6 +114,16 @@ defmodule Tableau.PostExtension do
   layout: "ElixirTools.PostLayout"
   ---
   ```
+
+  ## URL generation
+
+  If a `:permalink` is specified in the front matter, whatever is there _will_ be the post's permalink, regardless of presence of `:slug`
+
+  If `:slug` is specified, the globally configured permalink will be used, with the slug provided as a replacement string. See `Tableau.PostExtension.Config` for details.
+
+  If neither `:permalink` nor `:slug` is specified, the files name will be used as the slug.
+
+  In all cases, permalinks are stripped of non-alphanumeric characters.
   """
 
   {:ok, config} =