aws / aws/aws-cdk

(stack): (header tag breaking jsii-doc)

Open
#28,897 3 comments 0 reactions 0 assignees View on GitHub
bug documentation effort/medium p3
Dominant language
TypeScript
Stars
12.9k
Forks
4.6k
Avg merge
2d 3h
Merged PRs (30d)
83

Description

### Describe the issue

The header tags in [this inline documentation](https://github.com/aws/aws-cdk/blob/6a7a24afcc1ebebf71c267b890732a455e865cc8/packages/aws-cdk-lib/core/lib/stack.ts#L1174) are breaking `jsii-docgen` generated docs because they're being added as H2 tags on pages where they should probably H4 (if even headers at all). I know this isn't necessarily an AWS CDK issue, but if the header tags aren't really needed, it seems like an easy fix to remove it.

I mean does [this](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html#example-1) really need to be H2? 😅

### Links

https://github.com/aws/aws-cdk/blob/6a7a24afcc1ebebf71c267b890732a455e865cc8/packages/aws-cdk-lib/core/lib/stack.ts#L1174

Contributor guide

Open the contributing guide

Research direction

Inspect the inline documentation around line 1174 of packages/aws-cdk-lib/core/lib/stack.ts and compare its rendered output in the generated Stack documentation. Determine whether the header tags are needed, then verify that the resulting jsii-docgen page no longer renders the example as an inappropriate H2.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
documentation
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.