Attributes with multiple line Markdown descriptions are not aligned with list item

[bflad]

Terraform CLI and terraform-plugin-docs Versions

Latest Terraform version (1.13.5).

github.com/hashicorp/terraform-plugin-docs v0.22.0

Provider Code

func (r *APIDocumentResource) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) {
	resp.Schema = schema.Schema{
		MarkdownDescription: "APIDocument Resource",
		Attributes: map[string]schema.Attribute{
// ...
			"parent_document_id": schema.StringAttribute{
				Optional: true,
				MarkdownDescription: `API Documents may be rendered as a tree of files.` + "\n" +
					`` + "\n" +
					`Specify the ` + "`" + `id` + "`" + ` of another API Document as the ` + "`" + `parent_document_id` + "`" + ` to add some heirarchy do your documents.`,
			},

Expected Behavior

Given that terraform-plugin-docs is writing the attribute as a Markdown list item, multiple line text should be aligned with the line item automatically.

Actual Behavior

Additional lines of attribute descriptions are left-aligned (not indented) so the schema attribute list gets broken up into list items with bullets and padded left-aligned paragraphs. Especially with lengthy descriptions (e.g. with multiple paragraphs), its harder for practitioners to read.

One more trivial real world example:

Ideally, the schema markdown rendering of terraform-plugin-docs has context that its being written into a list with list item syntax and therefore should align the full description with the list item.

Its worth mentioning that these descriptions are being sourced from OpenAPI Specification documents, where the description may be used for other purposes and its difficult for API producers to know/understand tool-specific intricacies. A potential workaround is manually injecting space indentation characters into the Markdown description after multiple newline characters, however this may cause other tooling also using that description to be formatted unexpectedly.

Steps to Reproduce

Create any schema attribute MarkdownDescription with multiple, sequential newline characters.

How much impact is this issue causing?

Low

Logs

No response

Additional Information

No response

Code of Conduct

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

[rainkwan]

Hi @bflad we would definitely be open to contributions to fix this issue.

Based on what was described we could have a strategy where we make changes to the Markdown Description before handing it off to the package that generates the actual markdown. Perhaps we can detect if there are multiple consecutive newlines in a markdown list item and convert it into a single newline to fix the rendering.

Thank you again for raising this issue.

[Kim-Yukyung]

Hi @rainkwan, thank you for the guidance!

I’ve opened a pull request to address this issue #542 – feat: normalize consecutive newlines in markdown descriptions to preserve list formatting

The PR implements the suggested approach by normalizing multiple consecutive newlines before rendering the Markdown, ensuring consistent formatting within list items.

Please let me know if any adjustments are needed. Thanks again for your help!