From 821470a9e2566ec6c7b72a0f331feef76411f72b Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Tue, 28 Dec 2021 10:08:02 +0800 Subject: [PATCH 1/2] docs: recommend highlighting with comments than number range --- website/docs/docusaurus-core.md | 2 +- .../markdown-features-code-blocks.mdx | 108 +++++++++--------- 2 files changed, 54 insertions(+), 56 deletions(-) diff --git a/website/docs/docusaurus-core.md b/website/docs/docusaurus-core.md index dd2eaadbfb43..ec35ee065231 100644 --- a/website/docs/docusaurus-core.md +++ b/website/docs/docusaurus-core.md @@ -526,7 +526,7 @@ This is the most convenient hook to access plugin global data and should be used `pluginId` is optional if you don't use multi-instance plugins. ```ts -usePluginData(pluginName: string, pluginId?: string) +function usePluginData(pluginName: string, pluginId?: string); ``` Usage example: diff --git a/website/docs/guides/markdown-features/markdown-features-code-blocks.mdx b/website/docs/guides/markdown-features/markdown-features-code-blocks.mdx index 3150f91640df..da94b58e8054 100644 --- a/website/docs/guides/markdown-features/markdown-features-code-blocks.mdx +++ b/website/docs/guides/markdown-features/markdown-features-code-blocks.mdx @@ -109,28 +109,63 @@ You can refer to [Prism's official language definitions](https://github.com/Pris ## Line highlighting {#line-highlighting} -You can bring emphasis to certain lines of code by specifying line ranges after the language meta string (leave a space after the language). +### Highlighting with comments {#highlighting-with-comments} + +You can use comments with `highlight-next-line`, `highlight-start`, and `highlight-end` to select which lines are highlighted. - ```jsx {3} + ```jsx function HighlightSomeText(highlight) { if (highlight) { + // highlight-next-line return 'This text is highlighted!'; } return 'Nothing highlighted'; } + + function HighlightMoreText(highlight) { + // highlight-start + if (highlight) { + return 'This range is highlighted!'; + } + // highlight-end + + return 'Nothing highlighted'; + } ``` -```jsx {3} +```jsx function HighlightSomeText(highlight) { if (highlight) { + // highlight-next-line return 'This text is highlighted!'; } return 'Nothing highlighted'; } + +function HighlightMoreText(highlight) { + // highlight-start + if (highlight) { + return 'This range is highlighted!'; + } + // highlight-end + + return 'Nothing highlighted'; +} ``` +Supported commenting syntax: + +| Language | Syntax | +| ---------- | ------------------------ | +| JavaScript | `/* ... */` and `// ...` | +| JSX | `{/* ... */}` | +| Python | `# ...` | +| HTML | `` | + +If there's a syntax that is not currently supported, we are open to adding them! Pull requests welcome. + To accomplish this, Docusaurus adds the `docusaurus-highlight-code-line` class to the highlighted lines. You will need to define your own styling for this CSS, possibly in your `src/css/custom.css` with a custom background color which is dependent on your selected syntax highlighting theme. The color given below works for the default highlighting theme (Palenight), so if you are using another theme, you will have to tweak the color accordingly. ```css title="/src/css/custom.css" @@ -148,9 +183,9 @@ html[data-theme='dark'] .docusaurus-highlight-code-line { } ``` -### Multiple-line highlighting {#multiple-line-highlighting} +### Highlighting with metadata string -To highlight multiple lines, separate the line numbers by commas or use the range syntax to select a chunk of lines. This feature uses the `parse-number-range` library and you can find [more syntax](https://www.npmjs.com/package/parse-numeric-range) on their project details. +You can also specify highlighted line ranges within the language meta string (leave a space after the language). To highlight multiple lines, separate the line numbers by commas or use the range syntax to select a chunk of lines. This feature uses the `parse-number-range` library and you can find [more syntax](https://www.npmjs.com/package/parse-numeric-range) on their project details. ```jsx {1,4-6,11} import React from 'react'; @@ -180,62 +215,25 @@ function MyComponent(props) { export default MyComponent; ``` -### Highlighting with comments {#highlighting-with-comments} - -You can also use comments with `highlight-next-line`, `highlight-start`, and `highlight-end` to select which lines are highlighted. - - ```jsx - function HighlightSomeText(highlight) { - if (highlight) { - // highlight-next-line - return 'This text is highlighted!'; - } - - return 'Nothing highlighted'; - } +:::tip prefer comments - function HighlightMoreText(highlight) { - // highlight-start - if (highlight) { - return 'This range is highlighted!'; - } - // highlight-end +Prefer highlighting with comments where you can. This way, highlight is inlined in the code, and if you add/remove lines, you don't have to offset your line ranges. You also don't have to manually count the lines if your code block becomes long. - return 'Nothing highlighted'; +````diff +- ```jsx {3} ++ ```jsx {4} + function HighlightSomeText(highlight) { + if (highlight) { ++ console.log('Highlighted text found'); + return 'This text is highlighted!'; } - ``` - -```jsx -function HighlightSomeText(highlight) { - if (highlight) { - // highlight-next-line - return 'This text is highlighted!'; - } - - return 'Nothing highlighted'; -} -function HighlightMoreText(highlight) { - // highlight-start - if (highlight) { - return 'This range is highlighted!'; + return 'Nothing highlighted'; } - // highlight-end - - return 'Nothing highlighted'; -} -``` - -Supported commenting syntax: - -| Language | Syntax | -| ---------- | ------------------------ | -| JavaScript | `/* ... */` and `// ...` | -| JSX | `{/* ... */}` | -| Python | `# ...` | -| HTML | `` | + ``` +```` -If there's a syntax that is not currently supported, we are open to adding them! Pull requests welcome. +::: ## Interactive code editor {#interactive-code-editor} From c248b82fdb3bb110b45427d3a59c8ba0be7a64f7 Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Tue, 28 Dec 2021 10:42:55 +0800 Subject: [PATCH 2/2] quick fix --- packages/docusaurus-utils/src/markdownLinks.ts | 9 ++++++++- .../markdown-features/markdown-features-code-blocks.mdx | 4 +++- 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/packages/docusaurus-utils/src/markdownLinks.ts b/packages/docusaurus-utils/src/markdownLinks.ts index 6379d7cd3849..2938eef4e13b 100644 --- a/packages/docusaurus-utils/src/markdownLinks.ts +++ b/packages/docusaurus-utils/src/markdownLinks.ts @@ -45,9 +45,16 @@ export function replaceMarkdownLinks({ // Replace internal markdown linking (except in fenced blocks). let fencedBlock = false; + let lastCodeFence = ''; const lines = fileString.split('\n').map((line) => { if (line.trim().startsWith('```')) { - fencedBlock = !fencedBlock; + if (!fencedBlock) { + fencedBlock = true; + [lastCodeFence] = line.trim().match(/^`+/)!; + // If we are in a ````-fenced block, all ``` would be plain text instead of fences + } else if (line.trim().match(/^`+/)![0].length >= lastCodeFence.length) { + fencedBlock = false; + } } if (fencedBlock) { return line; diff --git a/website/docs/guides/markdown-features/markdown-features-code-blocks.mdx b/website/docs/guides/markdown-features/markdown-features-code-blocks.mdx index da94b58e8054..3361ba7b2b0a 100644 --- a/website/docs/guides/markdown-features/markdown-features-code-blocks.mdx +++ b/website/docs/guides/markdown-features/markdown-features-code-blocks.mdx @@ -217,7 +217,7 @@ export default MyComponent; :::tip prefer comments -Prefer highlighting with comments where you can. This way, highlight is inlined in the code, and if you add/remove lines, you don't have to offset your line ranges. You also don't have to manually count the lines if your code block becomes long. +Prefer highlighting with comments where you can. By inlining highlight in the code, you don't have to manually count the lines if your code block becomes long. If you add/remove lines, you also don't have to offset your line ranges. ````diff - ```jsx {3} @@ -233,6 +233,8 @@ Prefer highlighting with comments where you can. This way, highlight is inlined ``` ```` +In the future, we may extend the magic comment system and let you define custom directives and their functionalities. The magic comments would only be parsed if a highlight metastring is not present. + ::: ## Interactive code editor {#interactive-code-editor}