Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Prepend markdown anchor links with '#md:' #2413

Merged
merged 1 commit into from
Oct 28, 2023
Merged

Prepend markdown anchor links with '#md:' #2413

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions src/lib/output/themes/MarkedPlugin.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -195,6 +195,19 @@ output file :
if (!markedOptions.renderer) {
markedOptions.renderer = new Marked.Renderer();

markedOptions.renderer.link = (href, title, text) => {
// Prefix the #anchor links `#md:`.
href =
href
?.replace(/^#(?:md:)?(.+)/, "#md:$1")
.replace(/"/g, """) || "";
let html = `<a href="${href}"`;
if (title != null)
html += ` title="${title.replace(/"/g, "&quot;")}"`;
html += `>${text}</a>`;
Comment on lines +201 to +207
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Awkward to have to construct the HTML tag manually - not sure if marked or typedoc provides an API for this?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

marked doesn't, typedoc does via the jsx templating engine, I'll make that change after merging

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually... I think we can revert this annoying prefixing now! The minimal theme was removed a while ago, so I'm not sure there's a reason for it anymore...

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

... sadly not. I'd like to rework the renderer at some point to make this possible, but headings in comments still get linked. It feels like there ought to be some other non-terrible way to do this, that doesn't make us write different headings than npm/github does when rendering...

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps going the other direction would work; adding prefixes to the headings which typedoc "owns" (generates) and leaving the regular markdown ids unprefixed?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I considered that when first adding the prefix, but typedoc generates a lot of anchors, there are generally far, far fewer markdown header links.

return html;
};

markedOptions.renderer.heading = (text, level, _, slugger) => {
const slug = slugger.slug(text);
// Prefix the slug with an extra `md:` to prevent conflicts with TypeDoc's anchors.
Expand Down