Proposal to add custom notation type

.gitignore

@@ -3,3 +3,5 @@
 dist
 .idea/
 *.iml
+.vscode/
+vendor/

Makefile

@@ -1,6 +1,9 @@
 helm-docs:
 	go build github.com/norwoodj/helm-docs/cmd/helm-docs
 
+install:
+	go install github.com/norwoodj/helm-docs/cmd/helm-docs
+
 .PHONY: fmt
 fmt:
 	go fmt ./...

README.md

@@ -177,6 +177,9 @@ can be used as well:
 | chart.valuesHeader        | The heading for the chart values section |
 | chart.valuesTable         | A table of the chart's values parsed from the `values.yaml` file (see below) |
 | chart.valuesSection       | A section headed by the valuesHeader from above containing the valuesTable from above or "" if there are no values |
+| chart.valuesTableHtml     | Like `chart.valuesTable` but it is rendered as (X)HTML tags to allow further rendering customization, instead of markdown tables format. |
+| chart.valuesSectionHtml   | Like `chart.valuesSection` but uses `chart.valuesTableHtml` |
+| chart.valueDefaultColumnRender | This is a hook template if you want to redefine how helm-docs render the default values in `chart.valuesTableHtml` mode. This is especially useful when combined with (X)HTML tags, so that you can nicely format multiline default values, like YAML/JSON object tree snippet with codeblock syntax highlighter, which is not possible or difficult when using the markdown table format. It can be redefined in your template file. |
 
 The default internal template mentioned above uses many of these and looks like this:
 ```
@@ -333,3 +336,81 @@ configMap:
   # configMap."not real config param" -- A completely fake config parameter for a useful example
   not real config param: value
 ```
+
+### Advanced table rendering
+Some helm chart `values.yaml` uses complicated structure for the key/value 
+pairs. For example, it may uses a multiline string of Go template text instead 
+of plain strings. Some values might also refer to a certain YAML/JSON object 
+structure, like internal k8s value type, or an enum. For these use case, 
+a standard markdown table format might be inadequate and you want to use HTML
+tags to render the table.
+
+Some example use case on why you need advanced table rendering:
+
+ - Hyperlinking the value type to an anchor or HTML link somewhere for reference
+ - Collapsible value description using `<summary>` tags to save space
+ - Multiline default values as codeblocks, instead of one line JSON structure for readability
+ - Custom rendering, for colors, actions, bookmarking, cross-reference, etc
+ - Cascading the markdown file generated by helm-docs to be post-processed by Jamstack into a static HTML docs site.
+
+In order to accomodate this, `helm-docs` provides an extensible and flexible way to customize rendering.
+
+1. Use the HTML value renderer instead of the default markdown format
+
+You can use `chart.valuesSectionHtml` to render the values table as HTML tags,
+instead of using `chart.valuesSection`. Using HTML tables provides more 
+flexibility because it can be processed by markdown viewer as a nested blocks, 
+instead of one row per line. This allows you to customize how each columns in a 
+row are rendered.
+
+2. Overriding built-in templates
+
+You can always overrides or redefine built-in templates in your own `_templates.
+gotmpl` file. The built-in templates can be thought of as a template hook. 
+For example, if you need to change the HTML table, for example to add a new 
+column, or define maximum width/height, you can override `chart.valuesTableHtml`. Your overrides will then be called by `chart.valuesSectionHtml`.
+
+You can add your own rendering logic for each column. For example, we have `chart.valueDefaultColumnRender` that is used to render "default value" column for each rows. If you want to override how helm-docs render the 
+"type" column, just define your own rendering template and call it from
+`chart.valuesTableHtml` for each of the rows.
+
+3. Using the metadata of each rows of values
+
+Custom styling and rendering can be done as flexible as you want, but you 
+still need a metadata that describes each rows of values. You can access 
+this information from the templates.
+
+When you override `chart.valuesTableHtml`, as you can see in the original 
+definition in `func getValuesTableTemplates()` [pkg/document/template.go](pkg/document/template.go), we iterates each row of values.
+For each "Value", it is modeled as a struct defined in `valueRow` struct
+in [pkg/document/model.go](pkg/document/model.go). You can then use the 
+fields in your template.
+
+Some fields here are directly referenced from `values.yaml`:
+- `Key`: the full name of the key referenced in `values.yaml`
+- `Type`: the type of the value of the key in `values.yaml`. Can be automatically inferred from YAML structure, or annotated using `# -- (mytype)` where `mytype` can be any string that you refer as the type of the value.
+- `NotationType`: the notation of the type used to render the default value. If `Type` refers to the data type of the value, then `NotationType` refers to **how** this value should be written/rendered by helm-docs. Generally helm-docs only remembers the notation type, but it was the writer's responsibility to make a template tag to render a specific notation type. Annotate the key with `# @notationType -- (mynotation)` where `mynotation` is an identifier to tell the renderer how to write the value.
+- `Default`: this is the default value of the key, found from `values.yaml`. It is either inferred from the YAML structure or defined using `# @default -- my default value` annotation, in case you need to show other example values.
+- `Description`: this is the description of the key/value, taken from the comments found in the `values.yaml` for the referred key.
+- `LineNumber`: this is the line number associated with where the key is declared. You can use this to construct an anchor to the actual `values.yaml` file.
+
+Note that helm-docs only provides these information, but the default behaviour is to always render it in plain Markdown file to be viewed locally.
+
+4. Use markdown files generated by helm-docs as intermediary files to be processed further
+
+Public helm charts sometimes needs to be published as static content 
+instead of just stored in a repository. This is needed for helm users to 
+be able to view or browse the chart options and dependencies.
+
+It is often more than enough to just browse the chart values options on 
+git hosting that is able to render markdown files as a nice HTML page, like GitHub or GitLab. 
+However, for a certain use case, you may want to use your own 
+documentation generator to host or publish the output of helm-docs.
+
+If you use some kind of Jamstack like Gatsby or Hugo, you can use the 
+output of helm-docs as an input for these doc generator. A typical use 
+case is to override helm-docs built-in template so that it renders a 
+markdown or markdownX files to be processed by Gatsby or Hugo into 
+a static Web/Javascript page.
+
+For a more concrete examples on how to do these custom rendering, see [example here](./example-charts/custom-value-notation-type/README.md)

example-charts/custom-value-notation-type/Chart.yaml

@@ -0,0 +1,27 @@
+apiVersion: v2
+name: django
+version: 0.2.1
+appVersion: 3.1
+description: Generic chart for basic Django-based web app
+keywords:
+  - Django
+  - Web
+home: https://www.djangoproject.com/
+sources:
+  - https://github.com/django/django
+maintainers:
+  - name: Rizky Maulana Nugraha
+    email: [email protected]
+icon: https://raw.githubusercontent.com/kartoza/charts/master/assets/logo/django.png
+engine: gotpl
+dependencies:
+  - name: postgis
+    version: 0.2.1
+    repository: "file://../../postgis/v0.2.1"
+    condition: postgis.enabled
+    tags:
+      - database-backend
+      - postgis
+  - name: common
+    version: 1.0.0
+    repository: "file://../../common/v1.0.0"