mirror of
https://github.com/facebook/docusaurus.git
synced 2025-04-29 10:17:55 +02:00
feat(v2): ability to "escape" JSX in MDX files as code blocks (#4278)
* Fix MDX Crowdin issues by wrapping complex JSX in code blocks * Add a remark plugin to unwrap MDX code blocks * Update MDX Crowdin doc
This commit is contained in:
Sébastien Lorber
GitHub
parent
9e758308bb
commit
6811a72e72
13 changed files with 1071 additions and 12 deletions
|
|
@ -13,12 +13,13 @@ const matter = require('gray-matter');
|
|||
const stringifyObject = require('stringify-object');
|
||||
const slug = require('./remark/slug');
|
||||
const toc = require('./remark/toc');
|
||||
const unwrapMdxCodeBlocks = require('./remark/unwrapMdxCodeBlocks');
|
||||
const transformImage = require('./remark/transformImage');
|
||||
const transformLinks = require('./remark/transformLinks');
|
||||
|
||||
const DEFAULT_OPTIONS = {
|
||||
rehypePlugins: [],
|
||||
remarkPlugins: [emoji, slug, toc],
|
||||
remarkPlugins: [unwrapMdxCodeBlocks, emoji, slug, toc],
|
||||
};
|
||||
|
||||
module.exports = async function docusaurusMdxLoader(fileString) {
|
||||
|
|
|
|||
|
|
@ -0,0 +1,819 @@
|
|||
// Jest Snapshot v1, https://goo.gl/fbAQLP
|
||||
|
||||
exports[`unwrapMdxCodeBlocks should unwrap the mdx code blocks 1`] = `
|
||||
"# MDX code blocks test document
|
||||
|
||||
## Some basic markdown
|
||||
|
||||
text
|
||||
|
||||
[link](https://facebook.com)
|
||||
|
||||
**bold**
|
||||
|
||||
|
||||
|
||||
## Some basic MDX
|
||||
|
||||
import XYZ from 'xyz';
|
||||
|
||||
<XYZ abc=\\"1\\" def={[1, '42', {hello: 'world'}]} style={{color: 'red'}}>
|
||||
<span>Test</span>
|
||||
</XYZ>
|
||||
|
||||
## Some basic MDX code block
|
||||
|
||||
import Avatar from 'avatar';
|
||||
|
||||
<Avatar style={{color: 'red'}}>
|
||||
<div>Sebastien Lorber</div>
|
||||
</Avatar>
|
||||
|
||||
## Some complex MDX with nested code blocks
|
||||
|
||||
<Tabs
|
||||
defaultValue=\\"bash\\"
|
||||
values={[
|
||||
{ label: 'Bash', value: 'bash' },
|
||||
{ label: 'Windows', value: 'windows' },
|
||||
{ label: 'PowerShell', value: 'powershell' }
|
||||
]}>
|
||||
<TabItem value=\\"bash\\">
|
||||
|
||||
\`\`\`bash
|
||||
GIT_USER=<GITHUB_USERNAME> yarn deploy
|
||||
\`\`\`
|
||||
|
||||
</TabItem>
|
||||
<TabItem value=\\"windows\\">
|
||||
|
||||
\`\`\`batch
|
||||
cmd /C \\"set \\"GIT_USER=<GITHUB_USERNAME>\\" && yarn deploy\\"
|
||||
\`\`\`
|
||||
|
||||
</TabItem>
|
||||
<TabItem value=\\"powershell\\">
|
||||
|
||||
\`\`\`powershell
|
||||
cmd /C 'set \\"GIT_USER=<GITHUB_USERNAME>\\" && yarn deploy'
|
||||
\`\`\`
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Some complex MDX code block with nested code blocks
|
||||
|
||||
<Tabs
|
||||
defaultValue=\\"bash\\"
|
||||
values={[
|
||||
{ label: 'Bash', value: 'bash' },
|
||||
{ label: 'Windows', value: 'windows' },
|
||||
{ label: 'PowerShell', value: 'powershell' }
|
||||
]}>
|
||||
<TabItem value=\\"bash\\">
|
||||
|
||||
\`\`\`bash
|
||||
GIT_USER=<GITHUB_USERNAME> yarn deploy
|
||||
\`\`\`
|
||||
|
||||
</TabItem>
|
||||
<TabItem value=\\"windows\\">
|
||||
|
||||
\`\`\`batch
|
||||
cmd /C \\"set \\"GIT_USER=<GITHUB_USERNAME>\\" && yarn deploy\\"
|
||||
\`\`\`
|
||||
|
||||
</TabItem>
|
||||
<TabItem value=\\"powershell\\">
|
||||
|
||||
\`\`\`powershell
|
||||
cmd /C 'set \\"GIT_USER=<GITHUB_USERNAME>\\" && yarn deploy'
|
||||
\`\`\`
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
"
|
||||
`;
|
||||
|
||||
exports[`unwrapMdxCodeBlocks should unwrap the mdx code blocks AST 1`] = `
|
||||
Object {
|
||||
"children": Array [
|
||||
Object {
|
||||
"children": Array [
|
||||
Object {
|
||||
"position": Position {
|
||||
"end": Object {
|
||||
"column": 32,
|
||||
"line": 1,
|
||||
"offset": 31,
|
||||
},
|
||||
"indent": Array [],
|
||||
"start": Object {
|
||||
"column": 3,
|
||||
"line": 1,
|
||||
"offset": 2,
|
||||
},
|
||||
},
|
||||
"type": "text",
|
||||
"value": "MDX code blocks test document",
|
||||
},
|
||||
],
|
||||
"depth": 1,
|
||||
"position": Position {
|
||||
"end": Object {
|
||||
"column": 32,
|
||||
"line": 1,
|
||||
"offset": 31,
|
||||
},
|
||||
"indent": Array [],
|
||||
"start": Object {
|
||||
"column": 1,
|
||||
"line": 1,
|
||||
"offset": 0,
|
||||
},
|
||||
},
|
||||
"type": "heading",
|
||||
},
|
||||
Object {
|
||||
"children": Array [
|
||||
Object {
|
||||
"position": Position {
|
||||
"end": Object {
|
||||
"column": 23,
|
||||
"line": 3,
|
||||
"offset": 55,
|
||||
},
|
||||
"indent": Array [],
|
||||
"start": Object {
|
||||
"column": 4,
|
||||
"line": 3,
|
||||
"offset": 36,
|
||||
},
|
||||
},
|
||||
"type": "text",
|
||||
"value": "Some basic markdown",
|
||||
},
|
||||
],
|
||||
"depth": 2,
|
||||
"position": Position {
|
||||
"end": Object {
|
||||
"column": 23,
|
||||
"line": 3,
|
||||
"offset": 55,
|
||||
},
|
||||
"indent": Array [],
|
||||
"start": Object {
|
||||
"column": 1,
|
||||
"line": 3,
|
||||
"offset": 33,
|
||||
},
|
||||
},
|
||||
"type": "heading",
|
||||
},
|
||||
Object {
|
||||
"children": Array [
|
||||
Object {
|
||||
"position": Position {
|
||||
"end": Object {
|
||||
"column": 5,
|
||||
"line": 5,
|
||||
"offset": 61,
|
||||
},
|
||||
"indent": Array [],
|
||||
"start": Object {
|
||||
"column": 1,
|
||||
"line": 5,
|
||||
"offset": 57,
|
||||
},
|
||||
},
|
||||
"type": "text",
|
||||
"value": "text",
|
||||
},
|
||||
],
|
||||
"position": Position {
|
||||
"end": Object {
|
||||
"column": 5,
|
||||
"line": 5,
|
||||
"offset": 61,
|
||||
},
|
||||
"indent": Array [],
|
||||
"start": Object {
|
||||
"column": 1,
|
||||
"line": 5,
|
||||
"offset": 57,
|
||||
},
|
||||
},
|
||||
"type": "paragraph",
|
||||
},
|
||||
Object {
|
||||
"children": Array [
|
||||
Object {
|
||||
"children": Array [
|
||||
Object {
|
||||
"position": Position {
|
||||
"end": Object {
|
||||
"column": 6,
|
||||
"line": 7,
|
||||
"offset": 68,
|
||||
},
|
||||
"indent": Array [],
|
||||
"start": Object {
|
||||
"column": 2,
|
||||
"line": 7,
|
||||
"offset": 64,
|
||||
},
|
||||
},
|
||||
"type": "text",
|
||||
"value": "link",
|
||||
},
|
||||
],
|
||||
"position": Position {
|
||||
"end": Object {
|
||||
"column": 29,
|
||||
"line": 7,
|
||||
"offset": 91,
|
||||
},
|
||||
"indent": Array [],
|
||||
"start": Object {
|
||||
"column": 1,
|
||||
"line": 7,
|
||||
"offset": 63,
|
||||
},
|
||||
},
|
||||
"title": null,
|
||||
"type": "link",
|
||||
"url": "https://facebook.com",
|
||||
},
|
||||
],
|
||||
"position": Position {
|
||||
"end": Object {
|
||||
"column": 29,
|
||||
"line": 7,
|
||||
"offset": 91,
|
||||
},
|
||||
"indent": Array [],
|
||||
"start": Object {
|
||||
"column": 1,
|
||||
"line": 7,
|
||||
"offset": 63,
|
||||
},
|
||||
},
|
||||
"type": "paragraph",
|
||||
},
|
||||
Object {
|
||||
"children": Array [
|
||||
Object {
|
||||
"children": Array [
|
||||
Object {
|
||||
"position": Position {
|
||||
"end": Object {
|
||||
"column": 7,
|
||||
"line": 9,
|
||||
"offset": 99,
|
||||
},
|
||||
"indent": Array [],
|
||||
"start": Object {
|
||||
"column": 3,
|
||||
"line": 9,
|
||||
"offset": 95,
|
||||
},
|
||||
},
|
||||
"type": "text",
|
||||
"value": "bold",
|
||||
},
|
||||
],
|
||||
"position": Position {
|
||||
"end": Object {
|
||||
"column": 9,
|
||||
"line": 9,
|
||||
"offset": 101,
|
||||
},
|
||||
"indent": Array [],
|
||||
"start": Object {
|
||||
"column": 1,
|
||||
"line": 9,
|
||||
"offset": 93,
|
||||
},
|
||||
},
|
||||
"type": "strong",
|
||||
},
|
||||
],
|
||||
"position": Position {
|
||||
"end": Object {
|
||||
"column": 9,
|
||||
"line": 9,
|
||||
"offset": 101,
|
||||
},
|
||||
"indent": Array [],
|
||||
"start": Object {
|
||||
"column": 1,
|
||||
"line": 9,
|
||||
"offset": 93,
|
||||
},
|
||||
},
|
||||
"type": "paragraph",
|
||||
},
|
||||
Object {
|
||||
"children": Array [
|
||||
Object {
|
||||
"alt": "image",
|
||||
"position": Position {
|
||||
"end": Object {
|
||||
"column": 43,
|
||||
"line": 11,
|
||||
"offset": 145,
|
||||
},
|
||||
"indent": Array [],
|
||||
"start": Object {
|
||||
"column": 1,
|
||||
"line": 11,
|
||||
"offset": 103,
|
||||
},
|
||||
},
|
||||
"title": null,
|
||||
"type": "image",
|
||||
"url": "https://facebook.com/favicon.ico",
|
||||
},
|
||||
],
|
||||
"position": Position {
|
||||
"end": Object {
|
||||
"column": 43,
|
||||
"line": 11,
|
||||
"offset": 145,
|
||||
},
|
||||
"indent": Array [],
|
||||
"start": Object {
|
||||
"column": 1,
|
||||
"line": 11,
|
||||
"offset": 103,
|
||||
},
|
||||
},
|
||||
"type": "paragraph",
|
||||
},
|
||||
Object {
|
||||
"children": Array [
|
||||
Object {
|
||||
"position": Position {
|
||||
"end": Object {
|
||||
"column": 18,
|
||||
"line": 13,
|
||||
"offset": 164,
|
||||
},
|
||||
"indent": Array [],
|
||||
"start": Object {
|
||||
"column": 4,
|
||||
"line": 13,
|
||||
"offset": 150,
|
||||
},
|
||||
},
|
||||
"type": "text",
|
||||
"value": "Some basic MDX",
|
||||
},
|
||||
],
|
||||
"depth": 2,
|
||||
"position": Position {
|
||||
"end": Object {
|
||||
"column": 18,
|
||||
"line": 13,
|
||||
"offset": 164,
|
||||
},
|
||||
"indent": Array [],
|
||||
"start": Object {
|
||||
"column": 1,
|
||||
"line": 13,
|
||||
"offset": 147,
|
||||
},
|
||||
},
|
||||
"type": "heading",
|
||||
},
|
||||
Object {
|
||||
"position": Position {
|
||||
"end": Object {
|
||||
"column": 23,
|
||||
"line": 15,
|
||||
"offset": 188,
|
||||
},
|
||||
"indent": Array [],
|
||||
"start": Object {
|
||||
"column": 1,
|
||||
"line": 15,
|
||||
"offset": 166,
|
||||
},
|
||||
},
|
||||
"type": "import",
|
||||
"value": "import XYZ from 'xyz';",
|
||||
},
|
||||
Object {
|
||||
"position": Position {
|
||||
"end": Object {
|
||||
"column": 7,
|
||||
"line": 19,
|
||||
"offset": 287,
|
||||
},
|
||||
"indent": Array [
|
||||
1,
|
||||
1,
|
||||
],
|
||||
"start": Object {
|
||||
"column": 1,
|
||||
"line": 17,
|
||||
"offset": 190,
|
||||
},
|
||||
},
|
||||
"type": "jsx",
|
||||
"value": "<XYZ abc=\\"1\\" def={[1, '42', {hello: 'world'}]} style={{color: 'red'}}>
|
||||
<span>Test</span>
|
||||
</XYZ>",
|
||||
},
|
||||
Object {
|
||||
"children": Array [
|
||||
Object {
|
||||
"position": Position {
|
||||
"end": Object {
|
||||
"column": 29,
|
||||
"line": 21,
|
||||
"offset": 317,
|
||||
},
|
||||
"indent": Array [],
|
||||
"start": Object {
|
||||
"column": 4,
|
||||
"line": 21,
|
||||
"offset": 292,
|
||||
},
|
||||
},
|
||||
"type": "text",
|
||||
"value": "Some basic MDX code block",
|
||||
},
|
||||
],
|
||||
"depth": 2,
|
||||
"position": Position {
|
||||
"end": Object {
|
||||
"column": 29,
|
||||
"line": 21,
|
||||
"offset": 317,
|
||||
},
|
||||
"indent": Array [],
|
||||
"start": Object {
|
||||
"column": 1,
|
||||
"line": 21,
|
||||
"offset": 289,
|
||||
},
|
||||
},
|
||||
"type": "heading",
|
||||
},
|
||||
Object {
|
||||
"lang": "mdx-code-block",
|
||||
"meta": null,
|
||||
"position": Position {
|
||||
"end": Object {
|
||||
"column": 4,
|
||||
"line": 29,
|
||||
"offset": 442,
|
||||
},
|
||||
"indent": Array [
|
||||
1,
|
||||
1,
|
||||
1,
|
||||
1,
|
||||
1,
|
||||
1,
|
||||
],
|
||||
"start": Object {
|
||||
"column": 1,
|
||||
"line": 23,
|
||||
"offset": 319,
|
||||
},
|
||||
},
|
||||
"type": "code",
|
||||
"value": "import Avatar from 'avatar';
|
||||
|
||||
<Avatar style={{color: 'red'}}>
|
||||
<div>Sebastien Lorber</div>
|
||||
</Avatar>",
|
||||
},
|
||||
Object {
|
||||
"children": Array [
|
||||
Object {
|
||||
"position": Position {
|
||||
"end": Object {
|
||||
"column": 44,
|
||||
"line": 31,
|
||||
"offset": 487,
|
||||
},
|
||||
"indent": Array [],
|
||||
"start": Object {
|
||||
"column": 4,
|
||||
"line": 31,
|
||||
"offset": 447,
|
||||
},
|
||||
},
|
||||
"type": "text",
|
||||
"value": "Some complex MDX with nested code blocks",
|
||||
},
|
||||
],
|
||||
"depth": 2,
|
||||
"position": Position {
|
||||
"end": Object {
|
||||
"column": 44,
|
||||
"line": 31,
|
||||
"offset": 487,
|
||||
},
|
||||
"indent": Array [],
|
||||
"start": Object {
|
||||
"column": 1,
|
||||
"line": 31,
|
||||
"offset": 444,
|
||||
},
|
||||
},
|
||||
"type": "heading",
|
||||
},
|
||||
Object {
|
||||
"position": Position {
|
||||
"end": Object {
|
||||
"column": 25,
|
||||
"line": 40,
|
||||
"offset": 688,
|
||||
},
|
||||
"indent": Array [
|
||||
1,
|
||||
1,
|
||||
1,
|
||||
1,
|
||||
1,
|
||||
1,
|
||||
1,
|
||||
],
|
||||
"start": Object {
|
||||
"column": 1,
|
||||
"line": 33,
|
||||
"offset": 489,
|
||||
},
|
||||
},
|
||||
"type": "jsx",
|
||||
"value": "<Tabs
|
||||
defaultValue=\\"bash\\"
|
||||
values={[
|
||||
{ label: 'Bash', value: 'bash' },
|
||||
{ label: 'Windows', value: 'windows' },
|
||||
{ label: 'PowerShell', value: 'powershell' }
|
||||
]}>
|
||||
<TabItem value=\\"bash\\">",
|
||||
},
|
||||
Object {
|
||||
"lang": "bash",
|
||||
"meta": null,
|
||||
"position": Position {
|
||||
"end": Object {
|
||||
"column": 4,
|
||||
"line": 44,
|
||||
"offset": 740,
|
||||
},
|
||||
"indent": Array [
|
||||
1,
|
||||
1,
|
||||
],
|
||||
"start": Object {
|
||||
"column": 1,
|
||||
"line": 42,
|
||||
"offset": 690,
|
||||
},
|
||||
},
|
||||
"type": "code",
|
||||
"value": "GIT_USER=<GITHUB_USERNAME> yarn deploy",
|
||||
},
|
||||
Object {
|
||||
"position": Position {
|
||||
"end": Object {
|
||||
"column": 28,
|
||||
"line": 47,
|
||||
"offset": 782,
|
||||
},
|
||||
"indent": Array [
|
||||
1,
|
||||
],
|
||||
"start": Object {
|
||||
"column": 1,
|
||||
"line": 46,
|
||||
"offset": 742,
|
||||
},
|
||||
},
|
||||
"type": "jsx",
|
||||
"value": " </TabItem>
|
||||
<TabItem value=\\"windows\\">",
|
||||
},
|
||||
Object {
|
||||
"lang": null,
|
||||
"meta": null,
|
||||
"position": Position {
|
||||
"end": Object {
|
||||
"column": 8,
|
||||
"line": 51,
|
||||
"offset": 865,
|
||||
},
|
||||
"indent": Array [
|
||||
1,
|
||||
1,
|
||||
],
|
||||
"start": Object {
|
||||
"column": 1,
|
||||
"line": 49,
|
||||
"offset": 784,
|
||||
},
|
||||
},
|
||||
"type": "code",
|
||||
"value": "\`\`\`batch
|
||||
cmd /C \\"set \\"GIT_USER=<GITHUB_USERNAME>\\" && yarn deploy\\"
|
||||
\`\`\`",
|
||||
},
|
||||
Object {
|
||||
"position": Position {
|
||||
"end": Object {
|
||||
"column": 31,
|
||||
"line": 54,
|
||||
"offset": 910,
|
||||
},
|
||||
"indent": Array [
|
||||
1,
|
||||
],
|
||||
"start": Object {
|
||||
"column": 1,
|
||||
"line": 53,
|
||||
"offset": 867,
|
||||
},
|
||||
},
|
||||
"type": "jsx",
|
||||
"value": " </TabItem>
|
||||
<TabItem value=\\"powershell\\">",
|
||||
},
|
||||
Object {
|
||||
"lang": "powershell",
|
||||
"meta": null,
|
||||
"position": Position {
|
||||
"end": Object {
|
||||
"column": 4,
|
||||
"line": 58,
|
||||
"offset": 986,
|
||||
},
|
||||
"indent": Array [
|
||||
1,
|
||||
1,
|
||||
],
|
||||
"start": Object {
|
||||
"column": 1,
|
||||
"line": 56,
|
||||
"offset": 912,
|
||||
},
|
||||
},
|
||||
"type": "code",
|
||||
"value": "cmd /C 'set \\"GIT_USER=<GITHUB_USERNAME>\\" && yarn deploy'",
|
||||
},
|
||||
Object {
|
||||
"position": Position {
|
||||
"end": Object {
|
||||
"column": 8,
|
||||
"line": 61,
|
||||
"offset": 1008,
|
||||
},
|
||||
"indent": Array [
|
||||
1,
|
||||
],
|
||||
"start": Object {
|
||||
"column": 1,
|
||||
"line": 60,
|
||||
"offset": 988,
|
||||
},
|
||||
},
|
||||
"type": "jsx",
|
||||
"value": " </TabItem>
|
||||
</Tabs>",
|
||||
},
|
||||
Object {
|
||||
"children": Array [
|
||||
Object {
|
||||
"position": Position {
|
||||
"end": Object {
|
||||
"column": 55,
|
||||
"line": 63,
|
||||
"offset": 1064,
|
||||
},
|
||||
"indent": Array [],
|
||||
"start": Object {
|
||||
"column": 4,
|
||||
"line": 63,
|
||||
"offset": 1013,
|
||||
},
|
||||
},
|
||||
"type": "text",
|
||||
"value": "Some complex MDX code block with nested code blocks",
|
||||
},
|
||||
],
|
||||
"depth": 2,
|
||||
"position": Position {
|
||||
"end": Object {
|
||||
"column": 55,
|
||||
"line": 63,
|
||||
"offset": 1064,
|
||||
},
|
||||
"indent": Array [],
|
||||
"start": Object {
|
||||
"column": 1,
|
||||
"line": 63,
|
||||
"offset": 1010,
|
||||
},
|
||||
},
|
||||
"type": "heading",
|
||||
},
|
||||
Object {
|
||||
"lang": "mdx-code-block",
|
||||
"meta": null,
|
||||
"position": Position {
|
||||
"end": Object {
|
||||
"column": 5,
|
||||
"line": 95,
|
||||
"offset": 1585,
|
||||
},
|
||||
"indent": Array [
|
||||
1,
|
||||
1,
|
||||
1,
|
||||
1,
|
||||
1,
|
||||
1,
|
||||
1,
|
||||
1,
|
||||
1,
|
||||
1,
|
||||
1,
|
||||
1,
|
||||
1,
|
||||
1,
|
||||
1,
|
||||
1,
|
||||
1,
|
||||
1,
|
||||
1,
|
||||
1,
|
||||
1,
|
||||
1,
|
||||
1,
|
||||
1,
|
||||
1,
|
||||
1,
|
||||
1,
|
||||
1,
|
||||
1,
|
||||
1,
|
||||
],
|
||||
"start": Object {
|
||||
"column": 1,
|
||||
"line": 65,
|
||||
"offset": 1066,
|
||||
},
|
||||
},
|
||||
"type": "code",
|
||||
"value": "<Tabs
|
||||
defaultValue=\\"bash\\"
|
||||
values={[
|
||||
{ label: 'Bash', value: 'bash' },
|
||||
{ label: 'Windows', value: 'windows' },
|
||||
{ label: 'PowerShell', value: 'powershell' }
|
||||
]}>
|
||||
<TabItem value=\\"bash\\">
|
||||
|
||||
\`\`\`bash
|
||||
GIT_USER=<GITHUB_USERNAME> yarn deploy
|
||||
\`\`\`
|
||||
|
||||
</TabItem>
|
||||
<TabItem value=\\"windows\\">
|
||||
|
||||
\`\`\`batch
|
||||
cmd /C \\"set \\"GIT_USER=<GITHUB_USERNAME>\\" && yarn deploy\\"
|
||||
\`\`\`
|
||||
|
||||
</TabItem>
|
||||
<TabItem value=\\"powershell\\">
|
||||
|
||||
\`\`\`powershell
|
||||
cmd /C 'set \\"GIT_USER=<GITHUB_USERNAME>\\" && yarn deploy'
|
||||
\`\`\`
|
||||
|
||||
</TabItem>
|
||||
</Tabs>",
|
||||
},
|
||||
],
|
||||
"position": Object {
|
||||
"end": Object {
|
||||
"column": 1,
|
||||
"line": 96,
|
||||
"offset": 1586,
|
||||
},
|
||||
"start": Object {
|
||||
"column": 1,
|
||||
"line": 1,
|
||||
"offset": 0,
|
||||
},
|
||||
},
|
||||
"type": "root",
|
||||
}
|
||||
`;
|
||||
|
|
@ -0,0 +1,95 @@
|
|||
# MDX code blocks test document
|
||||
|
||||
## Some basic markdown
|
||||
|
||||
text
|
||||
|
||||
[link](https://facebook.com)
|
||||
|
||||
**bold**
|
||||
|
||||
|
||||
|
||||
## Some basic MDX
|
||||
|
||||
import XYZ from 'xyz';
|
||||
|
||||
<XYZ abc="1" def={[1, '42', {hello: 'world'}]} style={{color: 'red'}}>
|
||||
<span>Test</span>
|
||||
</XYZ>
|
||||
|
||||
## Some basic MDX code block
|
||||
|
||||
```mdx-code-block
|
||||
import Avatar from 'avatar';
|
||||
|
||||
<Avatar style={{color: 'red'}}>
|
||||
<div>Sebastien Lorber</div>
|
||||
</Avatar>
|
||||
```
|
||||
|
||||
## Some complex MDX with nested code blocks
|
||||
|
||||
<Tabs
|
||||
defaultValue="bash"
|
||||
values={[
|
||||
{ label: 'Bash', value: 'bash' },
|
||||
{ label: 'Windows', value: 'windows' },
|
||||
{ label: 'PowerShell', value: 'powershell' }
|
||||
]}>
|
||||
<TabItem value="bash">
|
||||
|
||||
```bash
|
||||
GIT_USER=<GITHUB_USERNAME> yarn deploy
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="windows">
|
||||
|
||||
```batch
|
||||
cmd /C "set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy"
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="powershell">
|
||||
|
||||
```powershell
|
||||
cmd /C 'set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Some complex MDX code block with nested code blocks
|
||||
|
||||
````mdx-code-block
|
||||
<Tabs
|
||||
defaultValue="bash"
|
||||
values={[
|
||||
{ label: 'Bash', value: 'bash' },
|
||||
{ label: 'Windows', value: 'windows' },
|
||||
{ label: 'PowerShell', value: 'powershell' }
|
||||
]}>
|
||||
<TabItem value="bash">
|
||||
|
||||
```bash
|
||||
GIT_USER=<GITHUB_USERNAME> yarn deploy
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="windows">
|
||||
|
||||
```batch
|
||||
cmd /C "set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy"
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="powershell">
|
||||
|
||||
```powershell
|
||||
cmd /C 'set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
````
|
||||
|
|
@ -0,0 +1,38 @@
|
|||
/**
|
||||
* Copyright (c) Facebook, Inc. and its affiliates.
|
||||
*
|
||||
* This source code is licensed under the MIT license found in the
|
||||
* LICENSE file in the root directory of this source tree.
|
||||
*/
|
||||
|
||||
import {join} from 'path';
|
||||
import remark from 'remark';
|
||||
import mdx from 'remark-mdx';
|
||||
import vfile from 'to-vfile';
|
||||
import plugin from '..';
|
||||
|
||||
const processFixture = async (name) => {
|
||||
const path = join(__dirname, 'fixtures', name);
|
||||
const file = await vfile.read(path);
|
||||
const result = await remark().use(mdx).use(plugin).process(file);
|
||||
return result.toString();
|
||||
};
|
||||
|
||||
const processFixtureAST = async (name) => {
|
||||
const path = join(__dirname, 'fixtures', name);
|
||||
const file = await vfile.read(path);
|
||||
return remark().use(mdx).use(plugin).parse(file);
|
||||
};
|
||||
|
||||
describe('unwrapMdxCodeBlocks', () => {
|
||||
test('should unwrap the mdx code blocks', async () => {
|
||||
const result = await processFixture('has-mdx-code-blocks.mdx');
|
||||
expect(result).toMatchSnapshot();
|
||||
});
|
||||
|
||||
// The AST output should be parsed correctly or the MDX loader won't work!
|
||||
test('should unwrap the mdx code blocks AST', async () => {
|
||||
const result = await processFixtureAST('has-mdx-code-blocks.mdx');
|
||||
expect(result).toMatchSnapshot();
|
||||
});
|
||||
});
|
||||
|
|
@ -0,0 +1,34 @@
|
|||
/**
|
||||
* Copyright (c) Facebook, Inc. and its affiliates.
|
||||
*
|
||||
* This source code is licensed under the MIT license found in the
|
||||
* LICENSE file in the root directory of this source tree.
|
||||
*/
|
||||
|
||||
const visit = require('unist-util-visit');
|
||||
|
||||
// This plugin is mostly to help integrating Docusaurus with translation systems
|
||||
// that do not support well MDX embedded JSX syntax (like Crowdin)
|
||||
// We wrap the JSX syntax in code blocks so that translation tools don't mess-up with the markup
|
||||
// But the JSX inside such code blocks should still be evaluated as JSX
|
||||
// See https://github.com/facebook/docusaurus/pull/4278
|
||||
function plugin() {
|
||||
const transformer = (root) => {
|
||||
visit(root, 'code', (node, _index, parent) => {
|
||||
if (node.lang === 'mdx-code-block') {
|
||||
const newChildrens = this.parse(node.value).children;
|
||||
|
||||
// Replace the mdx code block by its content, parsed
|
||||
parent.children.splice(
|
||||
parent.children.indexOf(node),
|
||||
1,
|
||||
...newChildrens,
|
||||
);
|
||||
}
|
||||
});
|
||||
};
|
||||
|
||||
return transformer;
|
||||
}
|
||||
|
||||
module.exports = plugin;
|
||||
|
|
@ -104,6 +104,7 @@ GitHub enterprise installations should work in the same manner as github.com; yo
|
|||
|
||||
Finally, to deploy your site to GitHub Pages, run:
|
||||
|
||||
````mdx-code-block
|
||||
<Tabs
|
||||
defaultValue="bash"
|
||||
values={[
|
||||
|
|
@ -133,6 +134,7 @@ cmd /C 'set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy'
|
|||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
````
|
||||
|
||||
### Triggering deployment with GitHub Actions
|
||||
|
||||
|
|
|
|||
|
|
@ -133,6 +133,7 @@ import ThemedImage from '@theme/ThemedImage';
|
|||
/>;
|
||||
```
|
||||
|
||||
```mdx-code-block
|
||||
import useBaseUrl from '@docusaurus/useBaseUrl';
|
||||
import ThemedImage from '@theme/ThemedImage';
|
||||
|
||||
|
|
@ -143,3 +144,4 @@ import ThemedImage from '@theme/ThemedImage';
|
|||
dark: useBaseUrl('/img/docusaurus_speed.svg'),
|
||||
}}
|
||||
/>
|
||||
```
|
||||
|
|
|
|||
|
|
@ -37,6 +37,7 @@ I can write **Markdown** alongside my _JSX_!
|
|||
|
||||
Notice how it renders both the markup from your React component and the Markdown syntax:
|
||||
|
||||
```mdx-code-block
|
||||
export const Highlight = ({children, color}) => (
|
||||
<span
|
||||
style={{
|
||||
|
|
@ -57,6 +58,7 @@ export const Highlight = ({children, color}) => (
|
|||
I can write **Markdown** alongside my _JSX_!
|
||||
|
||||
</BrowserWindow>
|
||||
```
|
||||
|
||||
<br />
|
||||
|
||||
|
|
|
|||
|
|
@ -332,13 +332,67 @@ Crowdin does not support well multiple concurrent uploads/downloads: it is prefe
|
|||
|
||||
### MDX
|
||||
|
||||
:::warning
|
||||
:::caution
|
||||
|
||||
Crowdin does not support the `.mdx` extension, and interpret these files as plain text instead of Markdown, producing a bad translation experience.
|
||||
Pay special attention to the JSX fragments in MDX documents!
|
||||
|
||||
:::
|
||||
|
||||
We temporarily recommend using the `.md` extension (even if the document contains React code), and are in touch with Crowdin to get this solved.
|
||||
Crowdin **does not support officially MDX**, but they added **support for the `.mdx` extension**, and interpret such files as Markdown (instead of plain text).
|
||||
|
||||
#### MDX problems
|
||||
|
||||
Crowdin thinks the JSX syntax is embedded HTML, and can mess-up with the JSX markup when you download the translations, leading to a site that fails to build due to invalid JSX.
|
||||
|
||||
Simple JSX fragments using simple string props like `<Username name="Sebastien"/>` will work fine.
|
||||
|
||||
More complex JSX fragments using object/array props like `<User person={{name: "Sebastien"}}/>` are more likely to fail due to a syntax that does not look like HTML.
|
||||
|
||||
#### MDX solutions
|
||||
|
||||
We recommend moving the complex embedded JSX code as separate standalone components.
|
||||
|
||||
We also added a `mdx-code-block` escape hatch syntax:
|
||||
|
||||
`````text
|
||||
# How to deploy Docusaurus
|
||||
|
||||
To deploy Docusaurus, run the following command:
|
||||
|
||||
````mdx-code-block
|
||||
import Tabs from '@theme/Tabs';
|
||||
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
<Tabs
|
||||
defaultValue="bash"
|
||||
values={[
|
||||
{ label: 'Bash', value: 'bash' },
|
||||
{ label: 'Windows', value: 'windows' }
|
||||
]}>
|
||||
<TabItem value="bash">
|
||||
|
||||
```bash
|
||||
GIT_USER=<GITHUB_USERNAME> yarn deploy
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="windows">
|
||||
|
||||
```batch
|
||||
cmd /C "set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy"
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
````
|
||||
`````
|
||||
|
||||
This will:
|
||||
|
||||
- be interpreted by Crowdin as code blocks (and not mess-up with the markup on download)
|
||||
- be interpreted by Docusaurus as regular JSX (as if it was not wrapped by any code block)
|
||||
- unfortunately opt-out of MDX tooling (IDE syntax highlighting, Prettier...)
|
||||
|
||||
### Docs versioning
|
||||
|
||||
|
|
|
|||
|
|
@ -94,6 +94,7 @@ Optional parameters, also set as environment variables:
|
|||
|
||||
Finally, to deploy your site to GitHub Pages, run:
|
||||
|
||||
````mdx-code-block
|
||||
<Tabs
|
||||
defaultValue="bash"
|
||||
values={[
|
||||
|
|
@ -123,6 +124,7 @@ cmd /C 'set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy'
|
|||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
````
|
||||
|
||||
### Triggering deployment with GitHub Actions
|
||||
|
||||
|
|
|
|||
|
|
@ -168,6 +168,7 @@ I can write **Markdown** alongside my _JSX_!
|
|||
|
||||
Notice how it renders both the markup from your React component and the Markdown syntax:
|
||||
|
||||
```mdx-code-block
|
||||
export const Highlight = ({children, color}) => (
|
||||
<span
|
||||
style={{
|
||||
|
|
@ -188,6 +189,7 @@ export const Highlight = ({children, color}) => (
|
|||
I can write **Markdown** alongside my _JSX_!
|
||||
|
||||
</BrowserWindow>
|
||||
```
|
||||
|
||||
<br />
|
||||
|
||||
|
|
@ -1106,6 +1108,7 @@ import ThemedImage from '@theme/ThemedImage';
|
|||
/>;
|
||||
```
|
||||
|
||||
```mdx-code-block
|
||||
import useBaseUrl from '@docusaurus/useBaseUrl';
|
||||
import ThemedImage from '@theme/ThemedImage';
|
||||
|
||||
|
|
@ -1116,3 +1119,4 @@ import ThemedImage from '@theme/ThemedImage';
|
|||
dark: useBaseUrl('img/docusaurus_speed.svg'),
|
||||
}}
|
||||
/>
|
||||
```
|
||||
|
|
|
|||
|
|
@ -94,6 +94,7 @@ Optional parameters, also set as environment variables:
|
|||
|
||||
Finally, to deploy your site to GitHub Pages, run:
|
||||
|
||||
````mdx-code-block
|
||||
<Tabs
|
||||
defaultValue="bash"
|
||||
values={[
|
||||
|
|
@ -123,6 +124,7 @@ cmd /C 'set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy'
|
|||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
````
|
||||
|
||||
### Triggering deployment with GitHub Actions
|
||||
|
||||
|
|
|
|||
|
|
@ -168,6 +168,7 @@ I can write **Markdown** alongside my _JSX_!
|
|||
|
||||
Notice how it renders both the markup from your React component and the Markdown syntax:
|
||||
|
||||
```mdx-code-block
|
||||
export const Highlight = ({children, color}) => (
|
||||
<span
|
||||
style={{
|
||||
|
|
@ -188,6 +189,7 @@ export const Highlight = ({children, color}) => (
|
|||
I can write **Markdown** alongside my _JSX_!
|
||||
|
||||
</BrowserWindow>
|
||||
```
|
||||
|
||||
<br />
|
||||
|
||||
|
|
@ -1161,6 +1163,7 @@ import ThemedImage from '@theme/ThemedImage';
|
|||
/>;
|
||||
```
|
||||
|
||||
```mdx-code-block
|
||||
import useBaseUrl from '@docusaurus/useBaseUrl';
|
||||
import ThemedImage from '@theme/ThemedImage';
|
||||
|
||||
|
|
@ -1171,3 +1174,4 @@ import ThemedImage from '@theme/ThemedImage';
|
|||
dark: useBaseUrl('img/docusaurus_speed.svg'),
|
||||
}}
|
||||
/>
|
||||
```
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue