docs: templating best practices#2397
Conversation
hairyhenderson
left a comment
hairyhenderson
left a comment
There was a problem hiding this comment.
@paradisfm thanks for working on this!
Apologies for the slow response. Overall this is good advice - I have a few very minor suggestions. Hopefully over time this can evolve to include more helpful usage patterns.
|
@hairyhenderson addressed comments - thanks for the feedback! never written "official" docs before so good to know docs-writing best practices as well :) |
Co-authored-by: Dave Henderson <dhenderson@gmail.com>
Co-authored-by: Dave Henderson <dhenderson@gmail.com>
|
This pull request is stale because it has been open for 60 days with If it's still relevant, one of the following will remove the stale
|
|
cheeky bump :( |
There was a problem hiding this comment.
Pull request overview
Adds a new documentation guide aimed at helping users write clearer, more maintainable Gomplate templates, based on the discussion in issue #2389.
Changes:
- Introduces a new “Best Practices in Templating” docs page.
- Provides practical guidance and examples for managing context, config divergence, conditionals, and reducing repetition.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| title: Best Practices in Templating | ||
| weight: 11 | ||
| menu: main |
There was a problem hiding this comment.
weight: 11 conflicts with the existing Usage page (also weight: 11), which can lead to unstable/undesired ordering in the main menu. Consider choosing an unused weight (e.g., 15) so the navigation order is deterministic.
| ### Using Environment Variables Effectively | ||
|
|
||
| You can and should create your own context using environment variables -- but choose them wisely. They should be overarching umbrellas that templates can share. |
There was a problem hiding this comment.
This page uses ### for the top-level section headings. Other pages in docs/content use ## for primary sections (with ### as subsections), which affects the generated TOC/heading hierarchy. Consider changing these top-level headings to ## for consistency.
| and set up the context: | ||
|
|
||
| ```gotemplate | ||
| {{- $env := env.Getenv "ENVIRONMENT" -}} |
There was a problem hiding this comment.
In this example, $PREFIX is referenced but never defined, so the snippet won’t work as-written. Consider defining it (e.g., via env.Getenv "PREFIX" or a literal file:///... base URL) before using it in printf.
| {{- $env := env.Getenv "ENVIRONMENT" -}} | |
| {{- $env := env.Getenv "ENVIRONMENT" -}} | |
| {{- $PREFIX := env.Getenv "PREFIX" -}} |
|
|
||
| ### Managing Config Divergence | ||
|
|
||
| When dealing with multiple groups of configs that behave differently from one another, you might be tempted to conditional your way out of it: |
There was a problem hiding this comment.
Grammar: “tempted to conditional your way out of it” reads incorrect/unclear. Consider rewording to something like “tempted to use conditionals everywhere” to improve readability.
| When dealing with multiple groups of configs that behave differently from one another, you might be tempted to conditional your way out of it: | |
| When dealing with multiple groups of configs that behave differently from one another, you might be tempted to use conditionals everywhere to handle the differences: |
| "dev1": "cloudprovisioner_iam", | ||
| "int2": "cloudprovisioner_iam", | ||
| "gov": "cloudprovisioner_iam", | ||
| "prod": "{{ index .TF_OUTPUTS_ALL_SERVICES \"cloud_provisioner\" \"db-user-name\" \"value\" }}" |
There was a problem hiding this comment.
The config.json example is not valid JSON as shown: it’s missing the closing braces for the db_users object and the top-level object (it ends after the prod entry). This makes the example copy/paste fail.
| "prod": "{{ index .TF_OUTPUTS_ALL_SERVICES \"cloud_provisioner\" \"db-user-name\" \"value\" }}" | |
| "prod": "{{ index .TF_OUTPUTS_ALL_SERVICES \"cloud_provisioner\" \"db-user-name\" \"value\" }}" | |
| } |
| **values.gtmpl:** | ||
|
|
||
| ```gotemplate | ||
| {{- defineDatasource "config" "/path/to/config/file" -}} |
There was a problem hiding this comment.
This defineDatasource example uses an absolute filesystem path without a file:/// scheme. Per the Datasources docs, the scheme may be omitted for relative paths, but absolute paths should use file:///.... Consider updating the example to avoid a non-working copy/paste.
| {{- defineDatasource "config" "/path/to/config/file" -}} | |
| {{- defineDatasource "config" "file:///path/to/config/file" -}} |
2 participants
following discussion on issue where i proposed "good templates 101" type docs #2389
i have spent a lot of time with gomplate and thought i would share some things i have learned (and definitely implemented, none of this was realized after the fact...) along the way.