Skip to content

doc: fix links to ECMAScript module resolution #52883

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

Closed
crawford wants to merge 3 commits into from
Closed

doc: fix links to ECMAScript module resolution #52883

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c375cf0
doc: mention quicker way to build docs
crawford May 7, 2024
490b02a
tools: support rewriting links in code blocks
crawford May 7, 2024
f125d7c
doc: fix links to ECMAScript module resolution
crawford May 7, 2024
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
Prev Previous commit
Next Next commit
tools: support rewriting links in code blocks 
Within the API documentation for modules, there is a section of
pseudo-code which contains links to another file. This pseudo-code is
inside of a pre-formatted element (`<pre>`), but that prevents the
build process from rewriting those links from the Markdown source to
their corresponding HTML output.

This addresses that by adding a new language, "pre", whose output
remains unformatted but allows code fences to be annotated with
metadata - code fences must have a language before the metadata. When
the right metadata ("html") is present, it indicates that the code
block should be processed so that anchor tags are rewritten just like
other references.

The actual change to the documentation will happen in a later commit.
  • Loading branch information
@crawford
crawford committed May 9, 2024
commit 490b02ac554a35b9cccb476255df2dfa29c81bf0
3 changes: 3 additions & 0 deletions tools/doc/html.mjs
View file
Open in desktop
Copy link
Copy Markdown
Member

@avivkeller avivkeller May 8, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

In my opinion, the change of this file warrants its own PR

Original file line number Diff line number Diff line change
Expand Up @@ -205,6 +205,7 @@ function linkJsTypeDocs(text) {
}

const isJSFlavorSnippet = (node) => node.lang === 'cjs' || node.lang === 'mjs';
const isPreSnippet = (node) => node.lang === 'pre';

// Preprocess headers, stability blockquotes, and YAML blocks.
export function preprocessElements({ filename }) {
Expand Down Expand Up @@ -265,6 +266,8 @@ export function preprocessElements({ filename }) {
// Isolated JS snippet, no need to add the checkbox.
node.value = `<pre>${highlighted} ${copyButton}</pre>`;
}
} else if (isPreSnippet(node)) {
node.value = `<pre>${node.value}</pre>`;
} else {
node.value = `<pre>${highlighted} ${copyButton}</pre>`;
}
Expand Down
9 changes: 9 additions & 0 deletions tools/doc/markdown.mjs
View file
Open in desktop
Copy link
Copy Markdown
Member

@avivkeller avivkeller May 8, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

In my opinion, the change of this file warrants its own PR

Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
import { visit } from 'unist-util-visit';

export const referenceToLocalMdFile = /^(?![+a-z]+:)([^#?]+)\.md(#.+)?$/i;
export const referenceToLocalMdFileInPre = /<a href="([^#"]+)\.md(#[^"]+)?">/g;

export function replaceLinks({ filename, linksMapper }) {
return (tree) => {
Expand All @@ -14,6 +15,14 @@ export function replaceLinks({ filename, linksMapper }) {
);
}
});
visit(tree, 'code', (node) => {
if (node.meta === 'html') {
node.value = node.value.replace(
referenceToLocalMdFileInPre,
(_, path, fragment) => `<a href="${path}.html${fragment || ''}">`,
);
}
});
visit(tree, 'definition', (node) => {
const htmlUrl = fileHtmlUrls && fileHtmlUrls[node.identifier];

Expand Down
1 change: 1 addition & 0 deletions tools/lint-md/lint-md.mjs
View file
Open in desktop
Copy link
Copy Markdown
Member

@avivkeller avivkeller May 8, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

In my opinion, the change of this file warrants its own PR

Original file line number Diff line number Diff line change
Expand Up @@ -23409,6 +23409,7 @@ const plugins = [
"markdown",
"mjs",
"powershell",
"pre",
"r",
"text",
"ts",
Expand Down