Skip to content

Commit

Permalink
feat(mdx-loader): add support for siteConfig.markdown.remarkRehypeOpt…
Browse files Browse the repository at this point in the history
…ions (#9674)
  • Loading branch information
slorber authored Dec 27, 2023
1 parent bd7d64f commit bfb882c
Show file tree
Hide file tree
Showing 10 changed files with 47 additions and 1 deletion.
1 change: 1 addition & 0 deletions packages/docusaurus-mdx-loader/src/processor.ts
Original file line number Diff line number Diff line change
Expand Up @@ -165,6 +165,7 @@ async function createProcessorFactory() {

const mdxProcessor = createMdxProcessor({
...processorOptions,
remarkRehypeOptions: options.markdownConfig.remarkRehypeOptions,
format,
});

Expand Down
1 change: 1 addition & 0 deletions packages/docusaurus-types/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@
},
"license": "MIT",
"dependencies": {
"@mdx-js/mdx": "^3.0.0",
"@types/history": "^4.7.11",
"@types/react": "*",
"commander": "^5.1.0",
Expand Down
10 changes: 10 additions & 0 deletions packages/docusaurus-types/src/config.d.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,10 @@ import type {Required as RequireKeys, DeepPartial} from 'utility-types';
import type {I18nConfig} from './i18n';
import type {PluginConfig, PresetConfig, HtmlTagObject} from './plugin';

import type {ProcessorOptions} from '@mdx-js/mdx';

export type RemarkRehypeOptions = ProcessorOptions['remarkRehypeOptions'];

export type ReportingSeverity = 'ignore' | 'log' | 'warn' | 'throw';

export type ThemeConfig = {
Expand Down Expand Up @@ -91,6 +95,12 @@ export type MarkdownConfig = {
* See also https://github.com/facebook/docusaurus/issues/4029
*/
mdx1Compat: MDX1CompatOptions;

/**
* Ability to provide custom remark-rehype options
* See also https://github.com/remarkjs/remark-rehype#options
*/
remarkRehypeOptions: RemarkRehypeOptions;
};

/**
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ exports[`loadSiteConfig website with .cjs siteConfig 1`] = `
"mermaid": false,
"parseFrontMatter": [Function],
"preprocessor": undefined,
"remarkRehypeOptions": undefined,
},
"noIndex": false,
"onBrokenLinks": "throw",
Expand Down Expand Up @@ -75,6 +76,7 @@ exports[`loadSiteConfig website with ts + js config 1`] = `
"mermaid": false,
"parseFrontMatter": [Function],
"preprocessor": undefined,
"remarkRehypeOptions": undefined,
},
"noIndex": false,
"onBrokenLinks": "throw",
Expand Down Expand Up @@ -124,6 +126,7 @@ exports[`loadSiteConfig website with valid JS CJS config 1`] = `
"mermaid": false,
"parseFrontMatter": [Function],
"preprocessor": undefined,
"remarkRehypeOptions": undefined,
},
"noIndex": false,
"onBrokenLinks": "throw",
Expand Down Expand Up @@ -173,6 +176,7 @@ exports[`loadSiteConfig website with valid JS ESM config 1`] = `
"mermaid": false,
"parseFrontMatter": [Function],
"preprocessor": undefined,
"remarkRehypeOptions": undefined,
},
"noIndex": false,
"onBrokenLinks": "throw",
Expand Down Expand Up @@ -222,6 +226,7 @@ exports[`loadSiteConfig website with valid TypeScript CJS config 1`] = `
"mermaid": false,
"parseFrontMatter": [Function],
"preprocessor": undefined,
"remarkRehypeOptions": undefined,
},
"noIndex": false,
"onBrokenLinks": "throw",
Expand Down Expand Up @@ -271,6 +276,7 @@ exports[`loadSiteConfig website with valid TypeScript ESM config 1`] = `
"mermaid": false,
"parseFrontMatter": [Function],
"preprocessor": undefined,
"remarkRehypeOptions": undefined,
},
"noIndex": false,
"onBrokenLinks": "throw",
Expand Down Expand Up @@ -320,6 +326,7 @@ exports[`loadSiteConfig website with valid async config 1`] = `
"mermaid": false,
"parseFrontMatter": [Function],
"preprocessor": undefined,
"remarkRehypeOptions": undefined,
},
"noIndex": false,
"onBrokenLinks": "throw",
Expand Down Expand Up @@ -371,6 +378,7 @@ exports[`loadSiteConfig website with valid async config creator function 1`] = `
"mermaid": false,
"parseFrontMatter": [Function],
"preprocessor": undefined,
"remarkRehypeOptions": undefined,
},
"noIndex": false,
"onBrokenLinks": "throw",
Expand Down Expand Up @@ -422,6 +430,7 @@ exports[`loadSiteConfig website with valid config creator function 1`] = `
"mermaid": false,
"parseFrontMatter": [Function],
"preprocessor": undefined,
"remarkRehypeOptions": undefined,
},
"noIndex": false,
"onBrokenLinks": "throw",
Expand Down Expand Up @@ -476,6 +485,7 @@ exports[`loadSiteConfig website with valid siteConfig 1`] = `
"mermaid": false,
"parseFrontMatter": [Function],
"preprocessor": undefined,
"remarkRehypeOptions": undefined,
},
"noIndex": false,
"onBrokenLinks": "throw",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -100,6 +100,7 @@ exports[`load loads props for site with custom i18n path 1`] = `
"mermaid": false,
"parseFrontMatter": [Function],
"preprocessor": undefined,
"remarkRehypeOptions": undefined,
},
"noIndex": false,
"onBrokenLinks": "throw",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,9 @@ describe('normalizeConfig', () => {
admonitions: false,
headingIds: true,
},
remarkRehypeOptions: {
footnoteLabel: 'Pied de page',
},
},
};
const normalizedConfig = normalizeConfig(userConfig);
Expand Down Expand Up @@ -514,6 +517,11 @@ describe('markdown', () => {
admonitions: true,
headingIds: false,
},
remarkRehypeOptions: {
footnoteLabel: 'Notes de bas de page',
// @ts-expect-error: we don't validate it on purpose
anyKey: 'heck we accept it on purpose',
},
};
expect(
normalizeConfig({
Expand Down
6 changes: 6 additions & 0 deletions packages/docusaurus/src/server/configValidation.ts
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ export const DEFAULT_MARKDOWN_CONFIG: MarkdownConfig = {
admonitions: true,
headingIds: true,
},
remarkRehypeOptions: undefined,
};

export const DEFAULT_CONFIG: Pick<
Expand Down Expand Up @@ -307,6 +308,11 @@ export const ConfigSchema = Joi.object<DocusaurusConfig>({
DEFAULT_CONFIG.markdown.mdx1Compat.headingIds,
),
}).default(DEFAULT_CONFIG.markdown.mdx1Compat),
remarkRehypeOptions:
// add proper external options validation?
// Not sure if it's a good idea, validation is likely to become stale
// See https://github.com/remarkjs/remark-rehype#options
Joi.object().unknown(),
}).default(DEFAULT_CONFIG.markdown),
}).messages({
'docusaurus.configValidationWarning':
Expand Down
2 changes: 2 additions & 0 deletions website/docs/api/docusaurus.config.js.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -436,6 +436,7 @@ type MarkdownConfig = {
preprocessor?: MarkdownPreprocessor;
parseFrontMatter?: ParseFrontMatter;
mdx1Compat: MDX1CompatOptions;
remarkRehypeOptions: object; // see https://github.com/remarkjs/remark-rehype#options
};
```

Expand Down Expand Up @@ -475,6 +476,7 @@ export default {
| `preprocessor` | `MarkdownPreprocessor` | `undefined` | Gives you the ability to alter the Markdown content string before parsing. Use it as a last-resort escape hatch or workaround: it is almost always better to implement a Remark/Rehype plugin. |
| `parseFrontMatter` | `ParseFrontMatter` | `undefined` | Gives you the ability to provide your own front matter parser, or to enhance the default parser. Read our [front matter guide](../guides/markdown-features/markdown-features-intro.mdx#front-matter) for details. |
| `mdx1Compat` | `MDX1CompatOptions` | `{comments: true, admonitions: true, headingIds: true}` | Compatibility options to make it easier to upgrade to Docusaurus v3+. |
| `remarkRehypeOptions` | `object` | `undefined` | Makes it possible to pass custom [`remark-rehype` options](https://github.com/remarkjs/remark-rehype#options). |
```mdx-code-block
</APITable>
Expand Down
4 changes: 4 additions & 0 deletions website/docusaurus.config.localized.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,5 +2,9 @@
"tagline": {
"en": "Build optimized websites quickly, focus on your content",
"fr": "Construisez rapidement des sites web optimisés, concentrez-vous sur votre contenu"
},
"remarkRehypeOptions_footnotes": {
"en": "Footnotes",
"fr": "Notes de bas de page"
}
}
5 changes: 4 additions & 1 deletion website/docusaurus.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,7 @@ const TwitterSvg =

const defaultLocale = 'en';

function getLocalizedConfigValue(key: string) {
function getLocalizedConfigValue(key: keyof typeof ConfigLocalized) {
const currentLocale = process.env.DOCUSAURUS_CURRENT_LOCALE ?? defaultLocale;
const values = ConfigLocalized[key];
if (!values) {
Expand Down Expand Up @@ -177,6 +177,9 @@ export default async function createConfigAsync() {
mdx1Compat: {
// comments: false,
},
remarkRehypeOptions: {
footnoteLabel: getLocalizedConfigValue('remarkRehypeOptions_footnotes'),
},
parseFrontMatter: async (params) => {
const result = await params.defaultParseFrontMatter(params);
return {
Expand Down

0 comments on commit bfb882c

Please sign in to comment.