docs: add docs on template

elixir-tools · Jul 18, 2024 · a4ccb8b · a4ccb8b
1 parent cff420c
commit a4ccb8b
Show file tree

Hide file tree

Showing 2 changed files with 49 additions and 5 deletions.
diff --git a/README.md b/README.md
@@ -1,6 +1,14 @@
-# TableauOgExtension
+# Tableau.OgExtension
 
-**TODO: Add description**
+[![Discord](https://img.shields.io/badge/Discord-5865F3?style=flat&logo=discord&logoColor=white&link=https://discord.gg/nNDMwTJ8)](https://discord.gg/6XdGnxVA2A)
+[![Hex.pm](https://img.shields.io/hexpm/v/tableau_og_extension)](https://hex.pm/packages/tableau_og_extension)
+[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/tableau_og_extension/)
+
+The Open Graph extension for Tableau!
+
+This enables you to create open graph images from a template for all of the pages in your site, utilizing [Puppeteer](https://pptr.dev/) and [Google Chrome](https://www.google.com/chrome/index.html).
+
+See the [docs](https://hexdocs.pm/tableau_og_extension/Tableau.OgExtension.html) for more information.
 
 ## Installation
 

diff --git a/lib/tableau/extensions/og_extension.ex b/lib/tableau/extensions/og_extension.ex
@@ -1,5 +1,5 @@
 defmodule Tableau.OgExtension do
-  @moduledoc """
+  @moduledoc ~S'''
   Extension to create Open Graph images.
 
   The Open Graph extension utilizes a user provided template, the Puppeteer Node.js module, and Google Chrome to 
@@ -26,19 +26,55 @@ defmodule Tableau.OgExtension do
 
   Subsequent runs will not regenerate existing images, so delete them first if you have changed your template.
 
+  ### Template
+
+  The extension will render a configured template into the image. The template is configured as a module/function tuple
+  that will be passed assigns including the Tableau page, which includes the title, permalink, etc.
+
+  Here is an example:
+
+  ```elixir
+  defmodule MySite.Og do
+    require EEx
+    EEx.function_from_string(
+      :def,
+      :template,
+      """
+      <!DOCTYPE html>
+      <html lang="en">
+        <head>
+          <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+          <meta charset="utf-8" />
+          <style>
+           <!-- my styles -->
+          </style>
+        </head>
+        <body >
+          <%= @page.title %> 
+        </body>
+      </html>
+      """,
+      [:assigns]
+    )
+  end
+  ```
+
+  Configuration example can be seen below.
+
   ## Configuration
 
-  Defaults are shown below.
+  Examples are shown below.
 
   ```elixir
   # config/config.exs
 
   config :tableau, Tableau.OgExtension,
     enabled: true,
     path: "./priv/og",
+    template: {MySite.Og, :template}
     log: true
   ```
-  """
+  '''
   use Tableau.Extension,
     enabled: true,
     key: :og,