Make most features work in CommonMark mode: head, live code blocks, tabs... #9092

slorber · 2023-06-22T15:12:54Z

Motivation

Related to the CommonMark support issue: #3018

Some custom elements we created do not work when using the CommonMark parser mode, that you can turn on using:

frontMatter.mdx.format: 'md'
config.markdown.format: 'detect' + using the .md extension

I think it would be convenient for users to have features working fine in both modes in a consistent way. I believe it is possible, but may require some adaptations.

Here are some components that do not currently work:

SEO

This should work in CommonMark too, but currently does not:

<head>
  <title>HEAD Markdown Page tests title</title>
  <meta name="keywords" content="cooking, blog">
</head>

Summary/details

Renders as:

Instead of:

Live code editor

Renders as:

Instead of:

Tabs

Renders as: N/A because we don't have any syntax that does not require using MDX/ESM imports.

Instead of:

Possible solution? IMHO this syntax should be allowed without imports:

<tabs>
  <tabItem value="apple" label="Apple" default>
    This is an apple 🍎
  </tabItem>
  <tabItem value="orange" label="Orange">
    This is an orange 🍊
  </tabItem>
  <tabItem value="banana" label="Banana">
    This is a banana 🍌
  </tabItem>
</tabs>

Structured data

As part of #9669 we are adding a @theme/StructuredData helper component:

import StructuredData from "@theme/StructuredData";

<head>
  <meta name="keywords" content="cooking, blog" />
  <meta name="twitter:card" content="summary_large_image" />
  <link rel="preconnect" href="https://example.com" />
  <StructuredData structuredData={{
    '@context': 'https://schema.org/',
    '@type': 'Organization',
    name: 'Meta Open Source',
    url: 'https://opensource.fb.com/',
    logo: 'https://opensource.fb.com/img/logos/Meta-Open-Source.svg',
  }} />
</head>

# Title

We should figure out how to define structured data in CommonMark mode

Self-service

I'd be willing to do some initial work on this proposal myself.

The text was updated successfully, but these errors were encountered:

Josh-Cena · 2023-06-22T15:17:09Z

Is my understanding correct that CommonMark mode does not allow providing custom components at all? If so, do we need to walk the React element tree created by mdx-loader in client code so we can inject our React components?

It seems rather imperative for us to make <details> and live code blocks work, but I'm not sure about tabs, considering we've always advocated them as an MDX-special feature, and people migrating from legacy (non-Docusaurus2) systems aren't likely going to use them anyway.

slorber · 2023-06-22T15:36:09Z

Is my understanding correct that CommonMark mode does not allow providing custom components at all?

It does not allow the usage of JSX when parsing the input, but it still compiles to React components, and you can process the AST so that it outputs what you want, reading components from the provider.

I recently added a few useful options to the MDX playground to make this easier to understand.

Note: when using the lowercase <summary>, the MDX rehype serializer output will not "read from the MDXProvider". To do so, we'd just have to capitalize it, and the output would then read from the MDXProvider and use the appropriate theme component.

What I mean is technically nothing prevents of from offering a feature parity for most of these features, so if we can, why not!

slorber · 2023-06-22T15:54:37Z

Hmmm my mistake, with CommonMark mode even lowercase elements seem to be able to read from the provider:

function _createMdxContent(props) {
  const _components = Object.assign({
    details: "details",
    summary: "summary",
    p: "p"
  }, props.components);
  return _jsxs(_components.details, {
    children: ["\n  ", _jsx(_components.summary, {
      children: "MD Summary"
    }), "\n", _jsx(_components.p, {
      children: "Our custom Details/Summary also works in CommonMark mode"
    }), "\n"]
  });
}

which is not the case for the mdx mode:

function _createMdxContent(props) {
  const _components = Object.assign({
    p: "p"
  }, props.components);
  return _jsxs("details", {
    children: [_jsx("summary", {
      children: "MD Summary"
    }), _jsx(_components.p, {
      children: "Our custom Details/Summary also works in CommonMark mode"
    })]
  });
}

I was able to make the details work in CommonMark by simply adding a lowercase details entry in the MDXProvider

slorber · 2023-06-22T15:57:24Z

Some elements like SEO <head> also seem quite critical to fix.

Unless we are able to fix all these critical elements fast, I think we can consider our CommonMark mode as "experimental" and eventually stabilize it in a further minor release. For v3 I think it's safer to keep the MDX parser by default even for .md files. Considering the CommonMark mode is new, that shouldn't be a problem for the community to adopt this mode incrementally.

Airkro · 2023-11-17T03:18:35Z

In my case, I make a remark plugin to using directive :docusaurus-doc-card-list to make <DocCardList /> work in docusaurus v3 CommonMark mode.

Maybe all the features can be landing as directive.

- these files used {string}, which is now evaluated as an expression in mdx (https://mdxjs.com/docs/what-is-mdx/#expressions) -> setup docusaurus to only use mdx on .mdx files, because api is generated as normal .md The docusaurus CommonMark feature is experimental: https://docusaurus.io/docs/markdown-features#mdx-vs-commonmark With following limitations:facebook/docusaurus#9092 For reference, failing files were: - "/api/Dalamud.Interface.Utility/Structs/ImVectorWrapper`T`" - "/api/Dalamud.Utility.Timing/Classes/Timings" - "/api/Dalamud.Utility/Classes/DisposeSafety.ScopedFinalizer" - "/api/FFXIVClientStructs.Interop/" - "/api/FFXIVClientStructs.Interop/Structs/SpanExtensions.SpanPointerEnumerator`T`"

* Bump docusaurus + update all dependencies: - docusaurus 3-alpha -> 3.4 - everything to latest, except: - eslint to v8, e.g. @typescript-eslint/parser doesn't support v9 yet - typescript ~5.4, because eslint v8 expects a version <5.5.0 - node >= 18 due to various dependencies dropping 16 Change prism-react-renderer import as necessary * Add @docusaurus/types as dev dependency - used in docusaurus.config.js already * Migration to husky v9 * Fix broken file (due to mdx3 being less lenient) * Update all used github actions: - due to warning from github to versions using node 20 * Change build pipeline to .NET 8 * Update pnpm to latest (9.4.0): Note: the new setup action now fails if a different version is used in package.json vs workflows config * workaround API build failing on 5 files: - these files used {string}, which is now evaluated as an expression in mdx (https://mdxjs.com/docs/what-is-mdx/#expressions) -> setup docusaurus to only use mdx on .mdx files, because api is generated as normal .md The docusaurus CommonMark feature is experimental: https://docusaurus.io/docs/markdown-features#mdx-vs-commonmark With following limitations:facebook/docusaurus#9092 For reference, failing files were: - "/api/Dalamud.Interface.Utility/Structs/ImVectorWrapper`T`" - "/api/Dalamud.Utility.Timing/Classes/Timings" - "/api/Dalamud.Utility/Classes/DisposeSafety.ScopedFinalizer" - "/api/FFXIVClientStructs.Interop/" - "/api/FFXIVClientStructs.Interop/Structs/SpanExtensions.SpanPointerEnumerator`T`" * Add 'bash' as additionalLanguage for prisms syntax highlighting: shell code wasn't highlighted, e.g. building/index.md * Update README: - Docusaurus 3 - always has been - with v3 pnpm build works locally when using --dev * Replace caution with warning due to deprecation in v3 * Change docusaurus.config.js to ES Module as recommended in the Migration Guide

slorber added proposal This issue is a proposal, usually non-trivial change status: needs triage This issue has not been triaged by maintainers labels Jun 22, 2023

Josh-Cena added domain: markdown Related to Markdown parsing or syntax and removed status: needs triage This issue has not been triaged by maintainers labels Jun 22, 2023

slorber mentioned this issue Jun 22, 2023

fix(theme): support details/summary in CommonMark + add md dogfood test cases #9093

Merged

slorber changed the title ~~Make all custom components work in CommonMark mode: details/summary, live code blocks...~~ Make all/most features work in CommonMark mode: head, live code blocks, tabs, mermaid... Jun 22, 2023

slorber changed the title ~~Make all/most features work in CommonMark mode: head, live code blocks, tabs, mermaid...~~ Make all/most features work in CommonMark mode: head, live code blocks, tabs... Jun 22, 2023

slorber changed the title ~~Make all/most features work in CommonMark mode: head, live code blocks, tabs...~~ Make most features work in CommonMark mode: head, live code blocks, tabs... Jun 22, 2023

This was referenced Jun 22, 2023

RFC: CommonMark compatibility, supporting multiple markdown/content parsers #3018

Closed

feat: upgrade to MDX v2 #8288

Merged

slorber mentioned this issue Sep 25, 2023

docs: the documentation, starter templates and tutorials should use the .mdx extension #8508

Closed

slorber mentioned this issue Feb 13, 2024

refactor(theme): use JSON-LD instead of microdata for blog structured data #9669

Merged

3 tasks

This comment was marked as off-topic.

Sign in to view

SayuShira mentioned this issue Jun 23, 2024

Update to Docusaurus 3.4 + dependencies goatcorp/dalamud-docs#29

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Make most features work in CommonMark mode: head, live code blocks, tabs... #9092

Make most features work in CommonMark mode: head, live code blocks, tabs... #9092

slorber commented Jun 22, 2023 •

edited

Loading

Josh-Cena commented Jun 22, 2023 •

edited

Loading

slorber commented Jun 22, 2023

slorber commented Jun 22, 2023

slorber commented Jun 22, 2023

Airkro commented Nov 17, 2023

This comment was marked as off-topic.

This comment was marked as off-topic.

This comment was marked as off-topic.

Make most features work in CommonMark mode: head, live code blocks, tabs... #9092

Make most features work in CommonMark mode: head, live code blocks, tabs... #9092

Comments

slorber commented Jun 22, 2023 • edited Loading

Motivation

SEO

Summary/details

Live code editor

Tabs

Structured data

Self-service

Josh-Cena commented Jun 22, 2023 • edited Loading

slorber commented Jun 22, 2023

slorber commented Jun 22, 2023

slorber commented Jun 22, 2023

Airkro commented Nov 17, 2023

This comment was marked as off-topic.

This comment was marked as off-topic.

This comment was marked as off-topic.

slorber commented Jun 22, 2023 •

edited

Loading

Josh-Cena commented Jun 22, 2023 •

edited

Loading