Use absolute guide links in inline comments

ocavue commented

2025-02-14 14:23:40 +01:00

(Migrated from github.com)

This PRs changes some links in comments from relative style (e.g. /docs/guide/#doc) to absolute style (e.g. https://prosemirror.net/docs/guide/#doc). While both styles of links work fine in the documentation site https://prosemirror.net/, in users' IDE, absolute links work better.

Before:

After:

An alternative way to implement this is adding a new option to @marijn/buildtool, like the existing expandLink option but it feels overkill.

This PRs changes some links in comments from relative style (e.g. `/docs/guide/#doc`) to absolute style (e.g. `https://prosemirror.net/docs/guide/#doc`). While both styles of links work fine in the documentation site https://prosemirror.net/, in users' IDE, absolute links work better. *Before:* <img width="921" alt="image" src="https://github.com/user-attachments/assets/7f52b8ed-3233-4979-9de3-b0789605ffb8" /> <img width="353" alt="image" src="https://github.com/user-attachments/assets/9041b74c-841f-415a-b5bb-27822a997dbe" /> *After:* <img width="942" alt="image" src="https://github.com/user-attachments/assets/bbac2b90-df24-4ef9-9b37-a9c55278897b" /> An alternative way to implement this is adding a new option to [`@marijn/buildtool`](https://github.com/marijnh/buildtool), like the existing [`expandLink`](https://github.com/marijnh/buildtool/blob/2c5a01026f3c364bc758809893d29f166aa5ae76/src/buildtool.ts#L24-L26) option but it feels overkill.

marijnh commented

2025-02-14 16:04:22 +01:00

(Migrated from github.com)

Where are you getting the .d.ts file that these comments come from? Because the ones on npm should all have these links expanded as part of the build process (and the raw source files use triple-slash comments, which, as far as I know, TypeScript won't pick up anyway).

ocavue commented

2025-02-14 17:05:26 +01:00

(Migrated from github.com)

Where are you getting the .d.ts file that these comments come from

https://unpkg.com/prosemirror-model@1.24.1/dist/index.d.ts

ones on npm should all have these links expanded as part of the build process

In the TypeScript source code, comments like [text](#model.MarkSpec.parseDOM) (shown in blue box above) will get processed, which make up the majority. However, comments like [text](/docs/guide/#schema.content_expressions) (shown in red box above) won't.

The build process that handles these links can be found below. Notice that only links that start with # get handled.

> Where are you getting the .d.ts file that these comments come from https://unpkg.com/prosemirror-model@1.24.1/dist/index.d.ts ![CleanShot 2025-02-15 at 02 57 24@2x](https://github.com/user-attachments/assets/16066c5f-1474-40b8-b5ca-e54e605217e2) --- > ones on npm should all have these links expanded as part of the build process In the TypeScript source code, comments like `[text](#model.MarkSpec.parseDOM)` (shown in blue box above) will get processed, which make up the majority. However, comments like `[text](/docs/guide/#schema.content_expressions)` (shown in red box above) won't. The build process that handles these links can be found below. Notice that only links that start with `#` get handled. - https://github.com/marijnh/buildtool/blob/2c5a01026f3c364bc758809893d29f166aa5ae76/src/buildtool.ts#L127 - https://github.com/ProseMirror/buildhelper/blob/593eda9b207432a3c481afd7d91362a75f3c995c/bin/pm-buildhelper.js#L15

marijnh commented

2025-02-14 17:37:56 +01:00

(Migrated from github.com)

Ahh right, these are links via the website root, not anchors. I'd say the build process could handle those too. Done in attached patch.

Pull request closed

This pull request cannot be reopened because the branch was deleted.

Rows
Columns

Use absolute guide links in inline comments #87

Pull request closed