Markdown reference link issue in generated Lit documentation
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 142
- Forks
- 230
- PR merge metrics
- No merged PRs in 30d
Description
### Issue
When generating documentation on Lit.dev we split jsdocs by newline. Creating a `shortText` description, and then a `text` description with the rest.
However this occurs before markdown is parsed which results in a malformed link if using [Reference Style Links](https://www.markdownguide.org/basic-syntax/#reference-style-links).
See bug in production on the Lit.dev generated directives page: https://lit.dev/docs/api/directives/#asyncReplace
Search for `[1]`.
See:
### Why
Because the [Markdown reference link in the Lit repository](https://github.com/lit/lit/blob/daddeb346a2f454b25a6a5d1722683197f25fbcd/packages/lit-html/src/directives/async-replace.ts#L110) gets split by the Lit.dev generator.
The usage of the reference is in the `shortText` field, but the reference itself ends up in the `text` field. Thus when generating HTML for `shortText`, the reference cannot be found because it is in the `text` field.
### Possible solution 1
Inline the link and remove the indirection of the reference. This fixes this one case and is probably the cheapest fix since we only have one or two reference link usages.
### Possible solution 2
Investigate if the Lit.dev API generator can be made robust to these links.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by inspecting the Lit.dev API generator flow that splits jsdocs before Markdown parsing, then reproduce the issue on the asyncReplace directive documentation and search for the [1] reference. Done means the generated page preserves and renders the reference-style link correctly without breaking shortText and text descriptions.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- documentation, tooling
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100