SchemaMarkdown contains wrong nested attribute titles

[sebhoss]

The generated schema information contains anchors in the form of <a id="nestedatt--..."></a> which are immediately followed by a markdown title in the form of ### Nested Schema for .... My expectation is that the attribute path in anchors match the attribute path in titles they precede but this does not seem to be the case. Instead the titles might contain the attribute path of a different attribute which is confusing for users.

I have an example generated with the latest version of tfplugindocs at https://github.com/metio/terraform-provider-k8s/blob/development/docs/data-sources/external_secrets_io_cluster_secret_store_v1alpha1_manifest.md?plain=1#L684-L709 showing the problem: The anchor nestedatt--spec--provider--oracle--auth--secret_ref--fingerprint is followed by a title pointing to spec.provider.oracle.auth.secret_ref.privatekey which is another attribute. In this case, the nested attributes of fingerprint and privatekey are exactly the same. The code for them is at https://github.com/metio/terraform-provider-k8s/blob/development/internal/provider/external_secrets_io_v1alpha1/external_secrets_io_secret_store_v1alpha1_manifest.go#L1891-L1955.

I've created a small test case at https://github.com/metio/terraform-provider-k8s/blob/development/internal/provider/provider_test.go#L23-L46 for that document and it shows multiple mismatches:

=== RUN   TestProviderDocumentation
    provider_test.go:43: Wanted [spec.provider.akeyless.auth_secret_ref] but got [spec.provider.akeyless.ca_provider]
    provider_test.go:43: Wanted [spec.provider.akeyless.ca_provider.kubernetes_auth.secret_ref] but got [spec.provider.akeyless.ca_provider.kubernetes_auth.service_account_ref]
    provider_test.go:43: Wanted [spec.provider.akeyless.ca_provider.secret_ref.access_id] but got [spec.provider.akeyless.ca_provider.secret_ref.access_type_param]
    provider_test.go:43: Wanted [spec.provider.akeyless.ca_provider.secret_ref.access_type] but got [spec.provider.akeyless.ca_provider.secret_ref.access_type_param]
    provider_test.go:43: Wanted [spec.provider.alibaba.auth] but got [spec.provider.alibaba.region_id]
    provider_test.go:43: Wanted [spec.provider.alibaba.region_id.secret_ref.access_key_id_secret_ref] but got [spec.provider.alibaba.region_id.secret_ref.access_key_secret_secret_ref]
    provider_test.go:43: Wanted [spec.provider.aws.auth] but got [spec.provider.aws.role]
    provider_test.go:43: Wanted [spec.provider.aws.role.secret_ref.access_key_id_secret_ref] but got [spec.provider.aws.role.secret_ref.secret_access_key_secret_ref]
    provider_test.go:43: Wanted [spec.provider.azurekv.auth_secret_ref] but got [spec.provider.azurekv.tenant_id]
    provider_test.go:43: Wanted [spec.provider.azurekv.service_account_ref] but got [spec.provider.azurekv.tenant_id]
    provider_test.go:43: Wanted [spec.provider.gcpsm.auth] but got [spec.provider.gcpsm.project_id]
    provider_test.go:43: Wanted [spec.provider.gcpsm.project_id.workload_identity.service_account_ref] but got [spec.provider.gcpsm.project_id.workload_identity.cluster_project_id]
    provider_test.go:43: Wanted [spec.provider.gitlab.auth] but got [spec.provider.gitlab.url]
    provider_test.go:43: Wanted [spec.provider.ibm.auth] but got [spec.provider.ibm.service_url]
    provider_test.go:43: Wanted [spec.provider.kubernetes.auth] but got [spec.provider.kubernetes.server]
    provider_test.go:43: Wanted [spec.provider.kubernetes.server.cert.client_cert] but got [spec.provider.kubernetes.server.cert.client_key]
    provider_test.go:43: Wanted [spec.provider.oracle.auth.secret_ref.fingerprint] but got [spec.provider.oracle.auth.secret_ref.privatekey]
    provider_test.go:43: Wanted [spec.provider.vault.auth] but got [spec.provider.vault.version]
    provider_test.go:43: Wanted [spec.provider.vault.version.cert.client_cert] but got [spec.provider.vault.version.cert.secret_ref]
    provider_test.go:43: Wanted [spec.provider.vault.version.jwt.kubernetes_service_account_token] but got [spec.provider.vault.version.jwt.secret_ref]
    provider_test.go:43: Wanted [spec.provider.vault.version.jwt.secret_ref.service_account_ref] but got [spec.provider.vault.version.jwt.secret_ref.expiration_seconds]
    provider_test.go:43: Wanted [spec.provider.vault.version.kubernetes.secret_ref] but got [spec.provider.vault.version.kubernetes.service_account_ref]
    provider_test.go:43: Wanted [spec.provider.vault.ca_provider] but got [spec.provider.vault.version]
    provider_test.go:43: Wanted [spec.provider.webhook.result] but got [spec.provider.webhook.timeout]
    provider_test.go:43: Wanted [spec.provider.webhook.ca_provider] but got [spec.provider.webhook.timeout]
    provider_test.go:43: Wanted [spec.provider.webhook.secrets] but got [spec.provider.webhook.timeout]
    provider_test.go:43: Wanted [spec.provider.yandexlockbox.auth] but got [spec.provider.yandexlockbox.ca_provider]

I'm not sure if this is a wrong expectation on my end, some problem with the schema of that provider or a bug in tfplugindocs, so any feedback is highly appreciated!

[github-actions]

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues.
If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.