From 658e487e2abf9a969d58585dbc6366012d00d5b9 Mon Sep 17 00:00:00 2001
From: Andrew Doble <andrew.l.doble@gmail.com>
Date: Fri, 25 Oct 2024 16:24:00 +0200
Subject: [PATCH] Writing TOCs

---
 doc/usage/Writing_TOC_Templates.md | 75 ++++++++++++++++++++++++++++++
 doc/usage/Writing_Templates.md     |  5 +-
 2 files changed, 79 insertions(+), 1 deletion(-)
 create mode 100644 doc/usage/Writing_TOC_Templates.md

diff --git a/doc/usage/Writing_TOC_Templates.md b/doc/usage/Writing_TOC_Templates.md
new file mode 100644
index 0000000..32797d8
--- /dev/null
+++ b/doc/usage/Writing_TOC_Templates.md
@@ -0,0 +1,75 @@
+# Writing a Template for a Table of Contents.
+
+Users can write their own templates for a table for contents (TOC) and specify that they should be used for TOCS by using `config` command or directly using the `-template`option, e.g.:
+
+```
+adr generate toc -template [My TOC Template]
+```
+
+Templates for table of contents use the [handlebars syntax](https://handlebarsjs.com/). Only a subset of this is described here. The fields available when generating TOCs are show in [ADR-J fields for TOCs](#adr-j-fields-for-tocs).  
+
+## Example TOC Template
+
+An example for a TOC template using the handlebars syntax is: 
+
+```markdown
+# List of ADRs 
+
+{{#entries}}
+* [ADR {{id}}]({{filename}}) : {{title}}
+{{/entries}}
+
+Created: {{date}}
+```
+
+
+## Field substitution
+
+`{{field}}` is substituted with the value of `field`, e.g.
+
+```
+* Created: {{date}}
+```
+After substitution this could look like:
+
+```
+* Created: 21 Oct 2024
+```
+
+Note the the date format depended on the `adr-j`configuration.
+
+## List substitution
+
+To iterate over the list of ADRs use the `{{#entries}}` and `{{/entries}}`  helpers. Any fields within this pair will refer to an ADR. For instance: 
+
+```
+{{#entries}}
+* ADR {{id}}
+{{/entries}}
+```
+could return a list of the ADRs identifiers:
+
+```
+- ADR 1
+- ADR 2
+- ADR 3
+- ADR 4
+```
+
+
+# ADR-J Fields for TOCs
+
+The following fields are used in generating TOCs:
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| `id` | field| The identifier of the ADR |
+| `filename` | field| The file name of the ADR |
+| `title` | field| The title of the ADR |
+| `date`| field | The current date |
+| `entries` | iterator | Iterator over each ADR |
+
+
+
+## 
+
diff --git a/doc/usage/Writing_Templates.md b/doc/usage/Writing_Templates.md
index e825665..440f25a 100644
--- a/doc/usage/Writing_Templates.md
+++ b/doc/usage/Writing_Templates.md
@@ -4,6 +4,9 @@ Users can write their own templates for the architecture decision records and sp
 
 Templates use their own markup for specifying the substitutions the `adr-j` tool uses.
 
+> [!NOTE]
+> Templates for table of contents (TOCs) use a different format. See [Writing TOC Templates](Writing_TOC_Templates.md).
+
 ## Field substitution
 
 `{{field}}` is substituted with the value of `field`, e.g.
@@ -43,7 +46,7 @@ The reasons the above is **not** valid are:
 * No link.id field
 * Fields are on separate lines.  
 
-## ADR-J fields
+## ADR-J fields for ADRs
 
 ### `id`