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

docs: document siteConfig.markdown + better mdx-loader retrocompat #8419

Merged
merged 3 commits into from
Dec 7, 2022
Merged

docs: document siteConfig.markdown + better mdx-loader retrocompat #8419

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
54adccb
document config.markdown + better mdx-loader retrocompat
slorber Dec 7, 2022
97833e4
document config.markdown + better mdx-loader retrocompat
slorber Dec 7, 2022
d5a0b79
document config.markdown + better mdx-loader retrocompat
slorber Dec 7, 2022
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 packages/docusaurus-mdx-loader/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,3 +44,16 @@ Array of remark plugins to manipulate the MDXAST
### `metadataPath`

A function to provide the metadataPath depending on current loaded MDX path that will be exported as the MDX metadata.

### `markdownConfig`

The global Docusaurus Markdown config (`config.markdown`), that plugin authors should forward:

```js
const loader = {
loader: require.resolve('@docusaurus/mdx-loader'),
options: {
markdownConfig: siteConfig.markdown,
},
};
```
2 changes: 1 addition & 1 deletion packages/docusaurus-mdx-loader/src/loader.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -173,7 +173,7 @@ export async function mdxLoader(
...(reqOptions.beforeDefaultRemarkPlugins ?? []),
...getAdmonitionsPlugins(reqOptions.admonitions ?? false),
...DEFAULT_OPTIONS.remarkPlugins,
...(reqOptions.markdownConfig.mermaid ? [mermaid] : []),
...(reqOptions.markdownConfig?.mermaid ? [mermaid] : []),
Copy link
Collaborator

Choose a reason for hiding this comment

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

This will be flagged by type-aware linting as unnecessary; we need to mark markdownConfig as optional in the options type. I'm not sure all this is necessary, though; markdownConfig is definitely required into the future.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

this is a bit unnecessary for sure but at least plugin authors will have less things breaking in v2

This will be flagged by type-aware linting as unnecessary;

We don't any anything being reported afaik, is this linting active?

I'm ok to just have this in v2, and remove this asap in v3 on the mdx 2 branch? We don't have to keep it, and it can be a temporary thing

Copy link
Collaborator

Choose a reason for hiding this comment

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

We don't any anything being reported afaik, is this linting active?

No, but I occasionally turn it on and fix reports locally. It's quite slow so I'm hesitant to add it to the CI.

I'm ok to just have this in v2, and remove this asap in v3 on the mdx 2 branch? We don't have to keep it, and it can be a temporary thing

That's reasonable, but people relying on internal APIs and coercing us to make changes sounds like a bad precedent. I'm okay to accept the change though.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

👍

Let's say it's not a commitment to always do this, and only a best effort we can do in case a small change from us can prevent a few plugins to break

Copy link
Collaborator

Choose a reason for hiding this comment

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

OK, but the type of Options.markdownConfig still needs to be marked as optional ^^

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

I'd rather not to. Somehow it's not optional, and we want users eventually using MDXLoaderOptions to be forced to provide it appropriately, and yet allow JS users to not have any runtime users. That sometimes makes sense to program defensively assuming all users (plugin authors here) won't use TS.

Copy link
Collaborator

Choose a reason for hiding this comment

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

That makes sense 👍

[
transformImage,
{
Expand Down
24 changes: 24 additions & 0 deletions website/docs/api/docusaurus.config.js.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -394,6 +394,30 @@ module.exports = {
};
```

### `markdown` {#markdown}

The global Docusaurus Markdown config.

- Type: `MarkdownConfig`

```ts
type MarkdownConfig = {
mermaid: boolean;
};
```

Example:

```js title="docusaurus.config.js"
module.exports = {
markdown: {
mermaid: true,
},
};
```

- `mermaid`: when `true`, allows Docusaurus to render Markdown code blocks with `mermaid` language as Mermaid diagrams.

### `customFields` {#customFields}

Docusaurus guards `docusaurus.config.js` from unknown fields. To add a custom field, define it on `customFields`.
Expand Down