Extra sections

[ramondeklein]

This PR allows adding extra sections to the documentation to allow adding markdown paragraphs to the documentation. This is often useful to elaborate on a specific setting in more detail. These extra sections are written using a header, so you also link to the section from the short documentation.

An example of such an extra definition is:

# @extra -- Volume Claim Template
# The volume claim template is used to create a `PersistentVolumeClaim` for the Key
# Manager pods. The amount of storage requested is specified in the `.spec.resources.requests.storage`
# field. The default value of '25Mi' should meet the requirements of reasonable production workloads.
#
# KeyManager may require more storage in workloads with a large number of enclaves and master keys.
# You can use the following formula to roughly estimate required storage:
# ```
# ( N_enclaves * 200 ) + ( N_keys * 200 ) + ( 64 * 1024 ) = total number of bytes
# ```
#
# More information about persistent volume claims can be found in
# [PersistentVolumeClaims](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims).

The actual field that describes the volume claim template can link to it using (see also [Volume Claim Templates](#volume-claim-template)) in the field description.

[Nepo26]

Firstly, thanks for the PR @ramondeklein, it may make things easier.

Things to improve

Documentation

Add an example under example-charts, it's a nice way to document what can be done.

Error

This seems to be breaking when used on a field that already has another comment giving this error:

❯ ../../helm-docs -t ../_templates.gotmpl -t ./README.md.gotmpl .
INFO[2025-12-13T17:15:36-03:00] Found Chart directories [.]
panic: runtime error: slice bounds out of range [1:0]

goroutine 42 [running]:
github.com/norwoodj/helm-docs/pkg/helm.ParseComment({0xcbf420?, 0x0, 0x0})
        /home/henriquene/git/personal/helm-docs/pkg/helm/comment.go:49 +0x5ee
github.com/norwoodj/helm-docs/pkg/helm.parseChartValuesFileComments({0xc00027c680, 0x1}, 0xc000342b40, {0x0, {0xc000312540, 0x3, 0x3}, {0xc00019f640, 0x3, 0x4}})
        /home/henriquene/git/personal/helm-docs/pkg/helm/chart_info.go:312 +0x650
github.com/norwoodj/helm-docs/pkg/helm.ParseChartInformation({_, _}, {_, {_, _, _}, {_, _, _}})
        /home/henriquene/git/personal/helm-docs/pkg/helm/chart_info.go:355 +0x36c
main.readDocumentationInfoByChartPath.func1({0x8302e0?, 0xc00019d240?})
        /home/henriquene/git/personal/helm-docs/cmd/helm-docs/main.go:107 +0x11c
main.parallelProcessIterable.func1()
        /home/henriquene/git/personal/helm-docs/cmd/helm-docs/main.go:35 +0x76
created by main.parallelProcessIterable in goroutine 1
        /home/henriquene/git/personal/helm-docs/cmd/helm-docs/main.go:32 +0x86

This is the example that I tried:

  # controller.persistentVolumeClaims -- List of persistent volume claims to create.
  # For very long comments, break them into multiple lines.
  # @default -- the chart will construct this list internally unless specified
  # @extra -- Volume Claim Template
  # The volume claim template is used to create a `PersistentVolumeClaim` for the Key
  # Manager pods. The amount of storage requested is specified in the `.spec.resources.requests.storage`
  # field. The default value of '25Mi' should meet the requirements of reasonable production workloads.
  #
  # KeyManager may require more storage in workloads with a large number of enclaves and master keys.
  # You can use the following formula to roughly estimate required storage:
  # ```
  # ( N_enclaves * 200 ) + ( N_keys * 200 ) + ( 64 * 1024 ) = total number of bytes
  # ```
  #
  # More information about persistent volume claims can be found in
  # [PersistentVolumeClaims](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims).
  persistentVolumeClaims: []

[ebuildy]

fantastic idea, I can finish it if you want!