Markdown and MDX configuration rework #5684

bholmesdev · 2022-12-27T23:29:00Z

Changes

Refine Markdown and MDX configuration options for ease-of-use. Decisions based on a discord feedback thread.

Markdown

Remove remark-smartypants from Astro's default Markdown plugins.
Replace the extendDefaultPlugins option with a simplified gfm boolean. This is enabled by default, and can be disabled to remove GitHub-Flavored Markdown.
Ensure GitHub-Flavored Markdown is applied whether or not custom remarkPlugins or rehypePlugins are configured. If you want to apply custom plugins and remove GFM, manually set gfm: false in your config.

MDX

Support all Markdown configuration options (except drafts) from your MDX integration config. This includes syntaxHighlighting and shikiConfig options to further customize the MDX renderer.
Simplify extendDefaults to an extendMarkdownConfig option. MDX options will be deeply merged with your Markdown config by default. By setting extendMarkdownConfig to false, you can "eject" to set your own syntax highlighting and plugins.

Testing

Update markdown-plugins and mdx-plugins test for new config extend options
Add MDX test for syntax highlight inheritance

Docs

Update Markdown configuration reference
Update MDX README
Update docs Update Markdown content docs for config rework docs#2280

changeset-bot · 2022-12-27T23:29:03Z

🦋 Changeset detected

Latest commit: aae0f82

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

bholmesdev · 2022-12-27T23:31:10Z

packages/markdown/remark/src/index.ts

 import { unified } from 'unified';
 import { VFile } from 'vfile';

 export { rehypeHeadingIds } from './rehype-collect-headings.js';
 export * from './types.js';

-export const DEFAULT_REMARK_PLUGINS = ['remark-gfm', 'remark-smartypants'];
-export const DEFAULT_REHYPE_PLUGINS = [];
+export const markdownConfigDefaults: Omit<Required<AstroMarkdownOptions>, 'drafts'> = {


Move markdownConfigDefaults to a const so Remark, Astro Core, and MDX can all share the same fallbacks!

lorenzolewis · 2022-12-27T23:35:02Z

I just put in this RFC discussion, I wonder if this might complement that withastro/roadmap#424

bholmesdev · 2022-12-27T23:45:30Z

@lorenzolewis thanks! That's a thorough set of ideas I think should be explored in future RFCs. Let me know if any changes proposed here would be blocking to your proposals. Otherwise, we'll treat this PR as step 1 on that journey!

sarah11918

I love this new config, @bholmesdev! Much more intuitive! 🥳

Some comments below!

packages/astro/src/@types/astro.ts

packages/integrations/mdx/README.md

sarah11918 · 2022-12-28T00:25:34Z

packages/integrations/mdx/README.md


-You can set remark-rehype options in your config file:
+For example, say you need to disable GitHub-Flavored Markdown and apply an extra remark plugin for MDX files. You can apply these options like so, with `extendMarkdownConfig` enabled by default:


I'm wondering whether these examples might be better suited to the docs page itself? I don't think these tell me anything new. They visually show what it looks like when both Markdown and MDX have config options set, but I'm not sure that's needed here?

The docs page here will need updating anyway, to correspond to these changes: /#configuring-markdown-and-mdx

Maybe what you have here as examples actually replaces what's there? Since that's where we show what it looks like when both have config settings are applied.

Agreed! I'll put a docs PR on-hold until we get a dev approval here. May be some final API reshuffling.

Alright, I think we have dev consensus. Moving to a docs PR!

sarah11918 · 2022-12-28T00:26:40Z

packages/integrations/mdx/README.md

 - [`recmaPlugins`](#recmaplugins)

-### `extendPlugins`
+### Markdown configuration options


nit: it feels weird to call these "Markdown configuration options"

I know this is shorthand for mirrors "all the stuff you can configure in Markdown, too!" but it really is MDX configuration options, that happen to (except for one 😅) be the exact same options that are available elsewhere for configuring Markdown.

I might be tempted to still, in fact, call this MDX configuration options. I think that's what it is. And, I think if people are searching for "MDX configuration" then having that in a header is helpful for our Algolia search results.

Hm, the overarching section is already MDX configuration, so I don't think that would make sense. I vote removing the heading if that's a concern 🤷

Update: renamed to "Options inherited from Markdown config" to clarify. If we don't like that heading, I say scrap it. I was just struggling with the table-of-contents feeling awkward without a heading present here.

delucis

In general, I think this direction is great! Won’t dive into the inline docs before we know we’re doing this, but left one comment that might help us think through these changes from the perspective of an (existing) user.

.changeset/shaggy-keys-turn.md

lorenzolewis · 2022-12-28T17:02:38Z

@bholmesdev I put some details on a possible enum value in the flag that could replace the markdown.githubFlavoredMarkdown config value in withastro/roadmap#424 (comment).

It might allow for more flexibility in the future without a major semver change, but 💯 up to your discretion if that's something you feel is relevant at this stage or not.

bholmesdev · 2022-12-28T18:26:10Z

@lorenzolewis thanks! I just left a comment on that enum suggestion.

To explain in context: I'm not sure I'm comfortable with blanket terms like basic or enhanced when we're unsure what use cases these will cover. I also have a feeling properties like githubFlavoredMarkdown will stick around even with this enum approach for finer tuning. For simplicity, I'd prefer to keep this PR as-is for the next major release. I think we can experiment with further Markdown features as a separate integration and even an experimental flag in Astro core for version 2.X.

.changeset/shaggy-keys-turn.md

bluwy

Looks good to me! Didn't see anything that stands out odd, and the new defaults looks great.

aFuzzyBear · 2023-01-02T16:05:07Z

.changeset/shaggy-keys-turn.md

+```
+
+
+Additionally, applying remark and rehype plugins **no longer disables** `githubFlavoredMarkdown`. You will need to opt-out manually by setting `githubFlavoredMarkdown` to `false`.


I really like this part

matthewp

Needs TSC approval.

matthewp

Approved by TSC.

bholmesdev · 2023-01-03T20:36:02Z

Approved by TSC.

Thanks TypeScript Compiler ❤️

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

* [ci] release * Wrap astro 2.0 beta logs in `<details>` * Add link to docs upgrade guide * First pass cleaning up 2.0 release notes * mdx changes from Sarah * combine 5584 and 5842 in deno, image, netlify * markdown/remark incl (5684 & 5769) to match mdx * Tweak markdown/remark formatting * Format astro-prism * Format astro-rss * Format create-astro * Format cloudflare * Format lit * Format partytown * Format node * Format preact * Format react * Format solid * Format svelte * Format tailwind * Format vercel * Format vue * Format telemetry * Format webapi * Format scripts * Reinstate h3s for headings Co-authored-by: Ben Holmes <hey@bholmes.dev> * Reformat mdx * astro & markdown/remark: Combine #5679 & #5684 changelogs Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com> Co-authored-by: Chris Swithinbank <swithinbank@gmail.com> Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca> Co-authored-by: Ben Holmes <hey@bholmes.dev>

* [ci] release * Update changelogs (#5955) * [ci] release * Wrap astro 2.0 beta logs in `<details>` * Add link to docs upgrade guide * First pass cleaning up 2.0 release notes * mdx changes from Sarah * combine 5584 and 5842 in deno, image, netlify * markdown/remark incl (5684 & 5769) to match mdx * Tweak markdown/remark formatting * Format astro-prism * Format astro-rss * Format create-astro * Format cloudflare * Format lit * Format partytown * Format node * Format preact * Format react * Format solid * Format svelte * Format tailwind * Format vercel * Format vue * Format telemetry * Format webapi * Format scripts * Reinstate h3s for headings Co-authored-by: Ben Holmes <hey@bholmes.dev> * Reformat mdx * astro & markdown/remark: Combine #5679 & #5684 changelogs Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com> Co-authored-by: Chris Swithinbank <swithinbank@gmail.com> Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca> Co-authored-by: Ben Holmes <hey@bholmes.dev> Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com> Co-authored-by: Matthew Phillips <matthew@skypack.dev> Co-authored-by: Chris Swithinbank <swithinbank@gmail.com> Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca> Co-authored-by: Ben Holmes <hey@bholmes.dev>

bholmesdev requested a review from a team as a code owner December 27, 2022 23:29

github-actions bot added pkg: astro Related to the core `astro` package (scope) pkg: integration Related to any renderer integration (scope) feat: markdown Related to Markdown (scope) labels Dec 27, 2022

bholmesdev commented Dec 27, 2022

View reviewed changes

sarah11918 reviewed Dec 28, 2022

View reviewed changes

delucis reviewed Dec 28, 2022

View reviewed changes

.changeset/shaggy-keys-turn.md Outdated Show resolved Hide resolved

EccentricVamp mentioned this pull request Dec 28, 2022

💡 RFC: Support a default layout #397

Closed

bholmesdev added the semver: major Change triggers a `major` release label Dec 30, 2022

bluwy reviewed Jan 2, 2023

View reviewed changes

.changeset/shaggy-keys-turn.md Outdated Show resolved Hide resolved

bluwy approved these changes Jan 2, 2023

View reviewed changes

bholmesdev force-pushed the feat/markdown-plugin-config-rework branch from 1944ffb to 2d5a774 Compare January 2, 2023 15:46

aFuzzyBear reviewed Jan 2, 2023

View reviewed changes

matthewp added needs discussion Issue needs to be discussed and removed needs discussion Issue needs to be discussed labels Jan 3, 2023

delucis approved these changes Jan 3, 2023

View reviewed changes

matthewp requested changes Jan 3, 2023

View reviewed changes

matthewp added needs discussion Issue needs to be discussed and removed needs discussion Issue needs to be discussed labels Jan 3, 2023

matthewp approved these changes Jan 3, 2023

View reviewed changes

bholmesdev added 4 commits January 3, 2023 16:32

feat: change extendDefaults -> gfm

d1523d6

deps: remove smartypants from md/remark

7b97880

tests: update markdown plugin tests

b97055c

fix: borked lockfile

10c84bd

bholmesdev and others added 19 commits January 3, 2023 16:36

refactor: move md defaults to remark

ef91b0a

fix: RemarkRehype type

351d86c

fix: apply defaults based on MD defaults

a8dfaf8

chore: update plugin tests

661980d

chore: add syntaxHighlight test

11b9970

refactor: remove drafts from config defaults

b9b4e1a

docs: new MDX config options

4bc9f11

chore: add changeset

2c8dca0

edit: test both extends for syntax highlight

641dbca

refactor: remove MDX config deep merge

35393ad

docs: update README and changeset

1ae5b72

edit: avoid -> disable

3a93e7d

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

edit: drafts clarification

063060a

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

edit: remove "scare quotes"

20f0dfc

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

docs: MDX config options redraft

d7858a2

docs: add migration

28fece6

chore: changeset heading levels

91edc65

refactor: githubFlavoredMarkdown -> gfm

4a2c2e7

chore: remove unused imports

aae0f82

bholmesdev force-pushed the feat/markdown-plugin-config-rework branch from 1514417 to aae0f82 Compare January 3, 2023 21:40

matthewp merged commit a9c2920 into main Jan 3, 2023

matthewp deleted the feat/markdown-plugin-config-rework branch January 3, 2023 22:12

astrobot-houston mentioned this pull request Jan 3, 2023

[ci] release (beta) #5732

Merged

bholmesdev mentioned this pull request Jan 5, 2023

Add SmartyPants flag #5769

Merged

sarah11918 mentioned this pull request Jan 24, 2023

Improve CHANGELOGs #5951

Merged

23 tasks

delucis added a commit that referenced this pull request Jan 24, 2023

astro & markdown/remark: Combine #5679 & #5684 changelogs

4138675

njakob mentioned this pull request Jan 31, 2023

Change of Remark plugins order for MDX integration after Astro 2.0 upgrade #6079

Closed

1 task

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Markdown and MDX configuration rework #5684

Markdown and MDX configuration rework #5684

bholmesdev commented Dec 27, 2022 •

edited

changeset-bot bot commented Dec 27, 2022 •

edited

bholmesdev Dec 27, 2022

lorenzolewis commented Dec 27, 2022

bholmesdev commented Dec 27, 2022

sarah11918 left a comment

sarah11918 Dec 28, 2022

bholmesdev Dec 28, 2022

bholmesdev Jan 3, 2023

sarah11918 Dec 28, 2022

bholmesdev Dec 28, 2022

bholmesdev Dec 28, 2022

delucis left a comment

lorenzolewis commented Dec 28, 2022

bholmesdev commented Dec 28, 2022

bluwy left a comment

aFuzzyBear Jan 2, 2023

matthewp left a comment

matthewp left a comment

bholmesdev commented Jan 3, 2023


		You can set remark-rehype options in your config file:
		For example, say you need to disable GitHub-Flavored Markdown and apply an extra remark plugin for MDX files. You can apply these options like so, with `extendMarkdownConfig` enabled by default:

		```


		Additionally, applying remark and rehype plugins no longer disables `githubFlavoredMarkdown`. You will need to opt-out manually by setting `githubFlavoredMarkdown` to `false`.

Markdown and MDX configuration rework #5684

Markdown and MDX configuration rework #5684

Conversation

bholmesdev commented Dec 27, 2022 • edited

Changes

Markdown

MDX

Testing

Docs

changeset-bot bot commented Dec 27, 2022 • edited

🦋 Changeset detected

Choose a reason for hiding this comment

lorenzolewis commented Dec 27, 2022

bholmesdev commented Dec 27, 2022

sarah11918 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

delucis left a comment

Choose a reason for hiding this comment

lorenzolewis commented Dec 28, 2022

bholmesdev commented Dec 28, 2022

bluwy left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

matthewp left a comment

Choose a reason for hiding this comment

matthewp left a comment

Choose a reason for hiding this comment

bholmesdev commented Jan 3, 2023

bholmesdev commented Dec 27, 2022 •

edited

changeset-bot bot commented Dec 27, 2022 •

edited