Ability to customize the `.SchemaMarkdown`

[mkilchhofer]

Terraform CLI and terraform-plugin-docs Versions

v0.21.0

Use Cases or Problem Statement

With other colleagues I maintain the TF provider to provision Applications inside Argo CD: https://github.com/argoproj-labs/terraform-provider-argocd

We have a very "big"/complex resource with a matrix generator:
https://github.com/argoproj-labs/terraform-provider-argocd/blob/main/docs/resources/application_set.md

Our "main" issue is that the size of this file is 1.3MiB and therefore 300KiB over the registry limit for a markdown file.

Specifically speaking, the same data structure appears on multiple levels inside the resource:

"metadata" (annotations, labels, name, namespace, finalizers)

### Nested Schema for `spec.generator.cluster_decision_resource.template.metadata`
### Nested Schema for `spec.generator.clusters.template.metadata`
### Nested Schema for `spec.generator.git.template.metadata`
### Nested Schema for `spec.generator.list.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.cluster_decision_resource.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.clusters.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.git.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.list.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.matrix.generator.cluster_decision_resource.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.matrix.generator.clusters.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.matrix.generator.git.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.matrix.generator.list.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.matrix.generator.plugin.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.matrix.generator.pull_request.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.matrix.generator.scm_provider.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.matrix.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.merge.generator.cluster_decision_resource.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.merge.generator.clusters.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.merge.generator.git.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.merge.generator.list.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.merge.generator.plugin.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.merge.generator.pull_request.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.merge.generator.scm_provider.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.merge.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.plugin.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.pull_request.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.scm_provider.template.metadata`
### Nested Schema for `spec.generator.matrix.template.metadata`
### Nested Schema for `spec.generator.merge.generator.cluster_decision_resource.template.metadata`
### Nested Schema for `spec.generator.merge.generator.clusters.template.metadata`
### Nested Schema for `spec.generator.merge.generator.git.template.metadata`
### Nested Schema for `spec.generator.merge.generator.list.template.metadata`
### Nested Schema for `spec.generator.merge.generator.matrix.generator.cluster_decision_resource.template.metadata`
### Nested Schema for `spec.generator.merge.generator.matrix.generator.clusters.template.metadata`
### Nested Schema for `spec.generator.merge.generator.matrix.generator.git.template.metadata`
### Nested Schema for `spec.generator.merge.generator.matrix.generator.list.template.metadata`
### Nested Schema for `spec.generator.merge.generator.matrix.generator.plugin.template.metadata`
### Nested Schema for `spec.generator.merge.generator.matrix.generator.pull_request.template.metadata`
### Nested Schema for `spec.generator.merge.generator.matrix.generator.scm_provider.template.metadata`
### Nested Schema for `spec.generator.merge.generator.matrix.template.metadata`
### Nested Schema for `spec.generator.merge.generator.merge.generator.cluster_decision_resource.template.metadata`
### Nested Schema for `spec.generator.merge.generator.merge.generator.clusters.template.metadata`
### Nested Schema for `spec.generator.merge.generator.merge.generator.git.template.metadata`
### Nested Schema for `spec.generator.merge.generator.merge.generator.list.template.metadata`
### Nested Schema for `spec.generator.merge.generator.merge.generator.plugin.template.metadata`
### Nested Schema for `spec.generator.merge.generator.merge.generator.pull_request.template.metadata`
### Nested Schema for `spec.generator.merge.generator.merge.generator.scm_provider.template.metadata`
### Nested Schema for `spec.generator.merge.generator.merge.template.metadata`
### Nested Schema for `spec.generator.merge.generator.plugin.template.metadata`
### Nested Schema for `spec.generator.merge.generator.pull_request.template.metadata`
### Nested Schema for `spec.generator.merge.generator.scm_provider.template.metadata`
### Nested Schema for `spec.generator.merge.template.metadata`
### Nested Schema for `spec.generator.plugin.template.metadata`
### Nested Schema for `spec.generator.pull_request.template.metadata`

"secret reference" (key, secret_name)

### Nested Schema for `spec.generator.matrix.generator.matrix.generator.pull_request.bitbucket_server.basic_auth.password_ref`
### Nested Schema for `spec.generator.matrix.generator.matrix.generator.pull_request.gitea.token_ref`
### Nested Schema for `spec.generator.matrix.generator.matrix.generator.pull_request.github.token_ref`
### Nested Schema for `spec.generator.matrix.generator.matrix.generator.pull_request.gitlab.token_ref`
### Nested Schema for `spec.generator.matrix.generator.matrix.generator.scm_provider.azure_devops.access_token_ref`
### Nested Schema for `spec.generator.matrix.generator.matrix.generator.scm_provider.bitbucket_cloud.app_password_ref`
### Nested Schema for `spec.generator.matrix.generator.matrix.generator.scm_provider.bitbucket_server.basic_auth.password_ref`
### Nested Schema for `spec.generator.matrix.generator.matrix.generator.scm_provider.gitea.token_ref`
### Nested Schema for `spec.generator.matrix.generator.matrix.generator.scm_provider.github.token_ref`
### Nested Schema for `spec.generator.matrix.generator.matrix.generator.scm_provider.gitlab.token_ref`
### Nested Schema for `spec.generator.matrix.generator.merge.generator.pull_request.bitbucket_server.basic_auth.password_ref`
### Nested Schema for `spec.generator.matrix.generator.merge.generator.pull_request.gitea.token_ref`
### Nested Schema for `spec.generator.matrix.generator.merge.generator.pull_request.github.token_ref`
### Nested Schema for `spec.generator.matrix.generator.merge.generator.pull_request.gitlab.token_ref`
### Nested Schema for `spec.generator.matrix.generator.merge.generator.scm_provider.azure_devops.access_token_ref`
### Nested Schema for `spec.generator.matrix.generator.merge.generator.scm_provider.bitbucket_cloud.app_password_ref`
### Nested Schema for `spec.generator.matrix.generator.merge.generator.scm_provider.bitbucket_server.basic_auth.password_ref`
### Nested Schema for `spec.generator.matrix.generator.merge.generator.scm_provider.gitea.token_ref`
### Nested Schema for `spec.generator.matrix.generator.merge.generator.scm_provider.github.token_ref`
### Nested Schema for `spec.generator.matrix.generator.merge.generator.scm_provider.gitlab.token_ref`
### Nested Schema for `spec.generator.matrix.generator.pull_request.bitbucket_server.basic_auth.password_ref`
### Nested Schema for `spec.generator.matrix.generator.pull_request.gitea.token_ref`
### Nested Schema for `spec.generator.matrix.generator.pull_request.github.token_ref`
### Nested Schema for `spec.generator.matrix.generator.pull_request.gitlab.token_ref`
### Nested Schema for `spec.generator.matrix.generator.scm_provider.azure_devops.access_token_ref`
### Nested Schema for `spec.generator.matrix.generator.scm_provider.bitbucket_cloud.app_password_ref`
### Nested Schema for `spec.generator.matrix.generator.scm_provider.bitbucket_server.basic_auth.password_ref`
### Nested Schema for `spec.generator.matrix.generator.scm_provider.gitea.token_ref`
### Nested Schema for `spec.generator.matrix.generator.scm_provider.github.token_ref`
### Nested Schema for `spec.generator.matrix.generator.scm_provider.gitlab.token_ref`
### Nested Schema for `spec.generator.merge.generator.matrix.generator.pull_request.bitbucket_server.basic_auth.password_ref`
### Nested Schema for `spec.generator.merge.generator.matrix.generator.pull_request.gitea.token_ref`
### Nested Schema for `spec.generator.merge.generator.matrix.generator.pull_request.github.token_ref`
### Nested Schema for `spec.generator.merge.generator.matrix.generator.pull_request.gitlab.token_ref`
### Nested Schema for `spec.generator.merge.generator.matrix.generator.scm_provider.azure_devops.access_token_ref`
### Nested Schema for `spec.generator.merge.generator.matrix.generator.scm_provider.bitbucket_cloud.app_password_ref`
### Nested Schema for `spec.generator.merge.generator.matrix.generator.scm_provider.bitbucket_server.basic_auth.password_ref`
### Nested Schema for `spec.generator.merge.generator.matrix.generator.scm_provider.gitea.token_ref`
### Nested Schema for `spec.generator.merge.generator.matrix.generator.scm_provider.github.token_ref`
### Nested Schema for `spec.generator.merge.generator.matrix.generator.scm_provider.gitlab.token_ref`
### Nested Schema for `spec.generator.merge.generator.merge.generator.pull_request.bitbucket_server.basic_auth.password_ref`
### Nested Schema for `spec.generator.merge.generator.merge.generator.pull_request.gitea.token_ref`
### Nested Schema for `spec.generator.merge.generator.merge.generator.pull_request.github.token_ref`
### Nested Schema for `spec.generator.merge.generator.merge.generator.pull_request.gitlab.token_ref`
### Nested Schema for `spec.generator.merge.generator.merge.generator.scm_provider.azure_devops.access_token_ref`
### Nested Schema for `spec.generator.merge.generator.merge.generator.scm_provider.bitbucket_cloud.app_password_ref`
### Nested Schema for `spec.generator.merge.generator.merge.generator.scm_provider.bitbucket_server.basic_auth.password_ref`
### Nested Schema for `spec.generator.merge.generator.merge.generator.scm_provider.gitea.token_ref`
### Nested Schema for `spec.generator.merge.generator.merge.generator.scm_provider.github.token_ref`
### Nested Schema for `spec.generator.merge.generator.merge.generator.scm_provider.gitlab.token_ref`
### Nested Schema for `spec.generator.merge.generator.pull_request.bitbucket_server.basic_auth.password_ref`
### Nested Schema for `spec.generator.merge.generator.pull_request.gitea.token_ref`
### Nested Schema for `spec.generator.merge.generator.pull_request.github.token_ref`
### Nested Schema for `spec.generator.merge.generator.pull_request.gitlab.token_ref`
### Nested Schema for `spec.generator.merge.generator.scm_provider.azure_devops.access_token_ref`
### Nested Schema for `spec.generator.merge.generator.scm_provider.bitbucket_cloud.app_password_ref`
### Nested Schema for `spec.generator.merge.generator.scm_provider.bitbucket_server.basic_auth.password_ref`
### Nested Schema for `spec.generator.merge.generator.scm_provider.gitea.token_ref`
### Nested Schema for `spec.generator.merge.generator.scm_provider.github.token_ref`
### Nested Schema for `spec.generator.merge.generator.scm_provider.gitlab.token_ref`
### Nested Schema for `spec.generator.pull_request.bitbucket_server.basic_auth.password_ref`
### Nested Schema for `spec.generator.pull_request.gitea.token_ref`
### Nested Schema for `spec.generator.pull_request.github.token_ref`
### Nested Schema for `spec.generator.pull_request.gitlab.token_ref`
### Nested Schema for `spec.generator.scm_provider.azure_devops.access_token_ref`
### Nested Schema for `spec.generator.scm_provider.bitbucket_cloud.app_password_ref`
### Nested Schema for `spec.generator.scm_provider.bitbucket_server.basic_auth.password_ref`
### Nested Schema for `spec.generator.scm_provider.gitea.token_ref`
### Nested Schema for `spec.generator.scm_provider.github.token_ref`
### Nested Schema for `spec.generator.scm_provider.gitlab.token_ref`

I count all nested schemas for this particular resource, we see 1645.

$ cat docs/resources/application_set.md  | grep 'Nested Schema for' | wc --lines
1645

Proposal

A way to define the structure once (I'd be okay to define those manually) and refenece from all links to exactly this one structure.

How much impact is this issue causing?

Medium

Additional Information

No response

Code of Conduct

• I agree to follow this project's Code of Conduct

Xref (to issue in TF provider repo):

• terraform docs: not working links on argocd_application_set argoproj-labs/terraform-provider-argocd#527