From dbd8cc4eb451561a1d5257d695dfbbe92c815d6e Mon Sep 17 00:00:00 2001
From: op-ct <chris.tessmer@onyxpoint.com>
Date: Tue, 10 May 2022 20:31:30 -0400
Subject: [PATCH] Add TOC to configuration docs (#1299)

Add TOC to configuration docs

The configuration doc is structured, but it's too large to easily
understand that structure.  It can be difficult for users to find their
way around without losing the context of the documentation they
eventually find, especially for beginners.

This patch adds a hyperlinked table of contents to the configuration
doc, to clarify the document's structure and provide an index of each
option with context.

Fixes #1298
---
 CHANGELOG.mkd                              |  1 +
 doc/dynamic-environments/configuration.mkd | 64 ++++++++++++++++++++++
 2 files changed, 65 insertions(+)

diff --git a/CHANGELOG.mkd b/CHANGELOG.mkd
index 926203360..cc7930810 100644
--- a/CHANGELOG.mkd
+++ b/CHANGELOG.mkd
@@ -3,6 +3,7 @@ CHANGELOG
 
 Unreleased
 ----------
+- Add TOC to configuration docs [#1298](https://github.com/puppetlabs/r10k/issues/1298)
 
 3.15.0
 ------
diff --git a/doc/dynamic-environments/configuration.mkd b/doc/dynamic-environments/configuration.mkd
index 67b29d6ad..f7abdea5f 100644
--- a/doc/dynamic-environments/configuration.mkd
+++ b/doc/dynamic-environments/configuration.mkd
@@ -1,6 +1,70 @@
 Dynamic Environment Configuration
 =================================
 
+<!-- vim-markdown-toc GFM -->
+
+* [Config file location](#config-file-location)
+  * [Manual configuration](#manual-configuration)
+  * [Automatic configuration](#automatic-configuration)
+* [General options](#general-options)
+  * [cachedir](#cachedir)
+  * [proxy](#proxy)
+  * [pool_size](#pool_size)
+  * [git](#git)
+    * [provider](#provider)
+    * [proxy](#proxy-1)
+    * [username](#username)
+    * [private_key](#private_key)
+    * [oauth_token](#oauth_token)
+    * [repositories](#repositories)
+      * [private_key](#private_key-1)
+      * [oauth_token](#oauth_token-1)
+      * [proxy](#proxy-2)
+  * [forge](#forge)
+    * [proxy](#proxy-3)
+    * [baseurl](#baseurl)
+    * [authorization_token](#authorization_token)
+    * [allow_puppetfile_override](#allow_puppetfile_override)
+* [Deployment options](#deployment-options)
+  * [postrun](#postrun)
+  * [sources](#sources)
+  * [deploy](#deploy)
+    * [purge\_levels](#purge_levels)
+      * [deployment](#deployment)
+      * [environment](#environment)
+      * [puppetfile](#puppetfile)
+    * [purge\_allowlist](#purge_allowlist)
+    * [write\_lock](#write_lock)
+    * [generate\_types](#generate_types)
+    * [puppet\_path](#puppet_path)
+    * [puppet\_conf](#puppet_conf)
+    * [exclude_spec](#exclude_spec)
+* [Source options](#source-options)
+  * [remote](#remote)
+  * [basedir](#basedir)
+  * [prefix](#prefix)
+    * [prefix behaviour](#prefix-behaviour)
+  * [strip\_component](#strip_component)
+    * [strip\_component behaviour](#strip_component-behaviour)
+  * [ignore_branch_prefixes](#ignore_branch_prefixes)
+    * [ignore_branch_prefixes behaviour](#ignore_branch_prefixes-behaviour)
+  * [filter_command](#filter_command)
+* [Examples](#examples)
+  * [Minimal example](#minimal-example)
+  * [Separate hiera data](#separate-hiera-data)
+  * [Multiple tenancy](#multiple-tenancy)
+    * [Multiple tenancy with external hieradata](#multiple-tenancy-with-external-hieradata)
+* [Experimental Features](#experimental-features)
+  * [YAML Environment Source](#yaml-environment-source)
+  * [YAMLdir Environment Source](#yamldir-environment-source)
+  * [Exec environment Source](#exec-environment-source)
+  * [Environment Modules](#environment-modules)
+    * [Puppetfile module conflicts](#puppetfile-module-conflicts)
+  * [Plain Environment Type](#plain-environment-type)
+  * [Tarball Environment Type](#tarball-environment-type)
+
+<!-- vim-markdown-toc -->
+
 R10k uses a configuration file to determine how dynamic environments should be
 deployed.