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.

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

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

Merged
merged 3 commits into from
Dec 7, 2022

Conversation

slorber
Copy link
Collaborator

@slorber slorber commented Dec 7, 2022

Motivation

Add missing siteConfig.markdown API ref doc

Improve retro compatibility as requested in #8298

Test Plan

preview

Test links

Deploy preview: https://deploy-preview-8419--docusaurus-2.netlify.app/docs/api/docusaurus-config#markdown

Related issues/PRs

#8298

@slorber slorber added the pr: documentation This PR works on the website or other text documents in the repo. label Dec 7, 2022
@facebook-github-bot facebook-github-bot added the CLA Signed Signed Facebook CLA label Dec 7, 2022
@slorber slorber added the to backport This PR is planned to be backported to a stable version of Docusaurus label Dec 7, 2022
@netlify
Copy link

netlify bot commented Dec 7, 2022

[V2]

Name Link
🔨 Latest commit d5a0b79
🔍 Latest deploy log https://app.netlify.com/sites/docusaurus-2/deploys/6390bdd581dad40009c0d37f
😎 Deploy Preview https://deploy-preview-8419--docusaurus-2.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

@github-actions
Copy link

github-actions bot commented Dec 7, 2022

⚡️ Lighthouse report for the deploy preview of this PR

URL Performance Accessibility Best Practices SEO PWA Report
/ 🟠 70 🟢 97 🟢 100 🟢 100 🟢 90 Report
/docs/installation 🟠 67 🟢 100 🟢 100 🟢 100 🟢 90 Report

@@ -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 👍

@github-actions
Copy link

github-actions bot commented Dec 7, 2022

Size Change: 0 B

Total Size: 886 kB

ℹ️ View Unchanged
Filename Size
website/.docusaurus/globalData.json 70.4 kB
website/build/assets/css/styles.********.css 112 kB
website/build/assets/js/main.********.js 663 kB
website/build/index.html 40.9 kB

compressed-size-action

@slorber slorber merged commit 59fac0b into main Dec 7, 2022
@slorber slorber deleted the slorber/doc-config-markdown branch December 7, 2022 16:59
@slorber slorber mentioned this pull request Dec 7, 2022
@slorber slorber removed the to backport This PR is planned to be backported to a stable version of Docusaurus label Jan 27, 2023
This was referenced Oct 19, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
CLA Signed Signed Facebook CLA pr: documentation This PR works on the website or other text documents in the repo.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants