lit / lit/lit.dev

Markdown reference link issue in generated Lit documentation

Open
#1,106 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

good first issue
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:
Screenshot 2023-05-09 at 2 58 08 PM

### 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.