diff --git a/templates/metadata.hcl.tmpl b/templates/metadata.hcl.tmpl
index cffc0ea..84fad8e 100644
--- a/templates/metadata.hcl.tmpl
+++ b/templates/metadata.hcl.tmpl
@@ -3,12 +3,49 @@
 metadata = {
   name                     = "{{ .Name }}"
   sql_name                 = "{{ .Name }}"
+
+  # TODO: Remove this comment block after customizing the file.
+  # `image_name`: MUST be unique across the container registry because
+  # it identifies the image (e.g. ghcr.io/cloudnative-pg/<image_name>)
   image_name               = "{{ .Name }}"
+
+  # TODO: Remove this comment block after customizing the file.
+  # `shared_preload_libraries`: list libraries to be added to
+  # `shared_preload_libraries` in Postgres. Usually empty.
+  # Used in tests.
+  # Example: ["pgaudit"].
   shared_preload_libraries = []
+
+  # TODO: Remove this comment block after customizing the file.
+  # `extension_control_path`: if EMPTY (`[]`), the operator follows the CNPG
+  # convention and will add the image's `share` directory to
+  # `extension_control_path`. Usually empty.
+  # Used in tests and to generate image catalogs.
+  # See: https://cloudnative-pg.io/docs/current/imagevolume_extensions#image-specifications
   extension_control_path   = []
+
+  # TODO: Remove this comment block after customizing the file.
+  # `dynamic_library_path`: if EMPTY (`[]`) the operator will add the image's
+  # `lib` directory to `dynamic_library_path`. Usually empty.
+  # Used in tests and to generate image catalogs.
   dynamic_library_path     = []
+
+  # TODO: Remove this comment block after customizing the file.
+  # `ld_library_path`: this SHOULD be defined when your extension needs
+  # additional (usually system) libraries loaded into Postgres before startup.
+  # If left EMPTY (`[]`) the operator will NOT alter `ld_library_path`. See the
+  # `postgis` extension metadata for an example usage. Usually empty.
+  # Used in tests and to generate image catalogs.
   ld_library_path          = []
+
+  # TODO: Remove this comment block after customizing the file.
+  # `auto_update_os_libs`: set to true to allow the maintenance tooling
+  # to update OS libraries automatically; look at the `postgis` example.
   auto_update_os_libs      = false
+
+  # TODO: Remove this comment block after customizing the file.
+  # `required_extensions`: must contain the name(s) of the sibling
+  # folders in this repository that contain a required extension.
   required_extensions      = []
 
   versions = {