From 83fe7ccc382da1d2df014c770309cbb847941edf Mon Sep 17 00:00:00 2001
From: Joe Mooring <joe.mooring@veriphor.com>
Date: Thu, 29 Aug 2024 12:39:29 -0700
Subject: [PATCH] Document table render hooks

See https://github.com/gohugoio/hugo/pull/12809.
---
 content/en/about/features.md            |   2 +-
 content/en/render-hooks/blockquotes.md  |   4 +-
 content/en/render-hooks/introduction.md |   5 +-
 content/en/render-hooks/tables.md       | 106 ++++++++++++++++++++++++
 4 files changed, 114 insertions(+), 3 deletions(-)
 create mode 100755 content/en/render-hooks/tables.md

diff --git a/content/en/about/features.md b/content/en/about/features.md
index 8353847237..58d3248536 100644
--- a/content/en/about/features.md
+++ b/content/en/about/features.md
@@ -49,7 +49,7 @@ toc: true
 : Leverage the embedded Markdown extensions to create tables, definition lists, footnotes, task lists, inserted text, mark text, subscripts, superscripts, and more.
 
 [Markdown render hooks]
-: Override the conversion of Markdown to HTML when rendering blockquotes, fenced code blocks, headings, images, and links. For example, render every standalone image as an HTML `figure` element.
+: Override the conversion of Markdown to HTML when rendering blockquotes, fenced code blocks, headings, images, links, and tables. For example, render every standalone image as an HTML `figure` element.
 
 [Diagrams]
 : Use fenced code blocks and Markdown render hooks to include diagrams in your content.
diff --git a/content/en/render-hooks/blockquotes.md b/content/en/render-hooks/blockquotes.md
index 607514f043..0bb6c438b0 100755
--- a/content/en/render-hooks/blockquotes.md
+++ b/content/en/render-hooks/blockquotes.md
@@ -59,7 +59,7 @@ block = true
 
 ###### PageInner
 
-(`page`) A reference to a page nested via the [`RenderShortcodes`] method.
+(`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
 
 [`RenderShortcodes`]: /methods/page/rendershortcodes
 
@@ -183,3 +183,5 @@ layouts/
         ├── render-blockquote-alert.html
         └── render-blockquote-regular.html
 ```
+
+{{% include "/render-hooks/_common/pageinner.md" %}}
diff --git a/content/en/render-hooks/introduction.md b/content/en/render-hooks/introduction.md
index 3745fc398d..2d1598fcb5 100755
--- a/content/en/render-hooks/introduction.md
+++ b/content/en/render-hooks/introduction.md
@@ -19,6 +19,7 @@ When rendering Markdown to HTML, render hooks override the conversion. Each rend
 - [Images](/render-hooks/images)
 - [Links](/render-hooks/links)
 - [Passthrough elements](/render-hooks/passthrough)
+- [Tables](/render-hooks/tables)
 
 {{% note %}}
 Hugo supports multiple [content formats] including Markdown, HTML, AsciiDoc, Emacs Org Mode, Pandoc, and reStructuredText.
@@ -60,7 +61,9 @@ layouts/
         ├── render-codeblock.html
         ├── render-heading.html
         ├── render-image.html
-        └── render-link.html    
+        ├── render-link.html
+        ├── render-passthrough.html
+        └── render-table.html
 ```
 
 The template lookup order allows you to create different render hooks for each page [type], [kind], language, and [output format]. For example:
diff --git a/content/en/render-hooks/tables.md b/content/en/render-hooks/tables.md
new file mode 100755
index 0000000000..a51640cd69
--- /dev/null
+++ b/content/en/render-hooks/tables.md
@@ -0,0 +1,106 @@
+---
+title: Table render hooks
+linkTitle: Tables
+description: Create a table render hook to override the rendering of Markdown tables to HTML.
+categories: [render hooks]
+keywords: []
+menu:
+  docs:
+    parent: render-hooks
+    weight: 90
+weight: 90
+toc: true
+---
+
+{{< new-in 0.134.0 >}}
+
+## Context
+
+Table render hook templates receive the following [context]:
+
+[context]: /getting-started/glossary/#context
+
+###### Attributes
+
+(`map`) The [Markdown attributes], available if you configure your site as follows:
+
+[Markdown attributes]: /content-management/markdown-attributes/
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.parser.attribute]
+block = true
+{{< /code-toggle >}}
+
+###### Ordinal
+
+(`int`) The zero-based ordinal of the table on the page.
+
+###### Page
+
+(`page`) A reference to the current page.
+
+###### PageInner
+
+(`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
+
+[`RenderShortcodes`]: /methods/page/rendershortcodes
+
+###### Position
+
+(`string`) The position of the table within the page content.
+
+###### THead
+(`slice`) A slice of table header rows, where each element is a slice of table cells.
+
+###### TBody
+(`slice`) A slice of table body rows, where each element is a slice of table cells.
+
+## Table cells
+
+Each table cell within the slice of slices returned by the `THead` and `TBody` methods has the following fields:
+
+###### Alignment
+(`string`) The alignment of the text within the table cell, one of `left`, `center`, or `right`.
+
+###### Text
+(`string`) The text within the table cell.
+
+## Example
+
+In its default configuration, Hugo renders Markdown tables according to the [GitHub Flavored Markdown specification]. To create a render hook that does the same thing:
+
+[GitHub Flavored Markdown specification]: https://github.github.com/gfm/#tables-extension-
+
+{{< code file=layouts/_default/_markup/render-table.html copy=true >}}
+<table
+  {{- range $k, $v := .Attributes }}
+    {{- if $v }}
+      {{- printf " %s=%q" $k $v | safeHTMLAttr }}
+    {{- end }}
+  {{- end }}>
+  <thead>
+    {{- range .THead }}
+      <tr>
+        {{- range . }}
+          <th {{ printf "style=%q" (printf "text-align: %s" .Alignment) | safeHTMLAttr }}>
+            {{- .Text | safeHTML -}}
+          </th>
+        {{- end }}
+      </tr>
+    {{- end }}
+  </thead>
+  <tbody>
+    {{- range .TBody }}
+      <tr>
+        {{- range . }}
+          <td {{ printf "style=%q" (printf "text-align: %s" .Alignment) | safeHTMLAttr }}>
+            {{- .Text | safeHTML -}}
+          </td>
+        {{- end }}
+      </tr>
+    {{- end }}
+  </tbody>
+</table>
+{{< /code >}}
+
+{{% include "/render-hooks/_common/pageinner.md" %}}