diff --git a/.changeset/shaggy-keys-turn.md b/.changeset/shaggy-keys-turn.md index c630eed48055c..66471e91976fe 100644 --- a/.changeset/shaggy-keys-turn.md +++ b/.changeset/shaggy-keys-turn.md @@ -9,8 +9,8 @@ Refine Markdown and MDX configuration options for ease-of-use. #### Markdown - **Remove `remark-smartypants`** from Astro's default Markdown plugins. -- **Replace the `extendDefaultPlugins` option** with a simplified `githubFlavoredMarkdown` boolean. This is enabled by default, and can be disabled to remove GFM. -- 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 `githubFlavoredMarkdown: false` in your config. +- **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 @@ -37,9 +37,9 @@ export default defineConfig({ }); ``` -##### Migrate `extendDefaultPlugins` to `githubFlavoredMarkdown` +##### Migrate `extendDefaultPlugins` to `gfm` -You may have disabled Astro's built-in plugins (GitHub-Flavored Markdown and Smartypants) with the `extendDefaultPlugins` option. Since Smartypants has been removed, this has been renamed to `githubFlavoredMarkdown`. +You may have disabled Astro's built-in plugins (GitHub-Flavored Markdown and Smartypants) with the `extendDefaultPlugins` option. Since Smartypants has been removed, this has been renamed to `gfm`. ```diff // astro.config.mjs @@ -48,16 +48,16 @@ import { defineConfig } from 'astro/config'; export default defineConfig({ markdown: { - extendDefaultPlugins: false, -+ githubFlavoredMarkdown: false, ++ gfm: false, } }); ``` -Additionally, applying remark and rehype plugins **no longer disables** `githubFlavoredMarkdown`. You will need to opt-out manually by setting `githubFlavoredMarkdown` to `false`. +Additionally, applying remark and rehype plugins **no longer disables** `gfm`. You will need to opt-out manually by setting `gfm` to `false`. ##### Migrate MDX's `extendPlugins` to `extendMarkdownConfig` You may have used the `extendPlugins` option to manage plugin defaults in MDX. This has been replaced by 2 flags: - `extendMarkdownConfig` (`true` by default) to toggle Markdown config inheritance. This replaces the `extendPlugins: 'markdown'` option. -- `githubFlavoredMarkdown` (`true` by default) to toggle GitHub-Flavored Markdown in MDX. This replaces the `extendPlugins: 'defaults'` option. +- `gfm` (`true` by default) to toggle GitHub-Flavored Markdown in MDX. This replaces the `extendPlugins: 'defaults'` option. diff --git a/packages/astro/src/@types/astro.ts b/packages/astro/src/@types/astro.ts index cba0a0dd123f1..fc350a77e425c 100644 --- a/packages/astro/src/@types/astro.ts +++ b/packages/astro/src/@types/astro.ts @@ -783,21 +783,21 @@ export interface AstroUserConfig { rehypePlugins?: RehypePlugins; /** * @docs - * @name markdown.githubFlavoredMarkdown + * @name markdown.gfm * @type {boolean} * @default `true` * @description - * Astro uses [GitHub-flavored Markdown](https://github.com/remarkjs/remark-gfm) by default. To disable this, set the `githubFlavoredMarkdown` flag to `false`: + * Astro uses [GitHub-flavored Markdown](https://github.com/remarkjs/remark-gfm) by default. To disable this, set the `gfm` flag to `false`: * * ```js * { * markdown: { - * githubFlavoredMarkdown: false, + * gfm: false, * } * } * ``` */ - githubFlavoredMarkdown?: boolean; + gfm?: boolean; /** * @docs * @name markdown.remarkRehype diff --git a/packages/astro/src/core/config/schema.ts b/packages/astro/src/core/config/schema.ts index 9673313c7a370..17e04053f8cae 100644 --- a/packages/astro/src/core/config/schema.ts +++ b/packages/astro/src/core/config/schema.ts @@ -179,9 +179,7 @@ export const AstroConfigSchema = z.object({ .custom((data) => data instanceof Object && !Array.isArray(data)) .optional() .default(ASTRO_CONFIG_DEFAULTS.markdown.remarkRehype), - githubFlavoredMarkdown: z - .boolean() - .default(ASTRO_CONFIG_DEFAULTS.markdown.githubFlavoredMarkdown), + gfm: z.boolean().default(ASTRO_CONFIG_DEFAULTS.markdown.gfm), }) .default({}), vite: z diff --git a/packages/astro/test/astro-markdown-plugins.test.js b/packages/astro/test/astro-markdown-plugins.test.js index 553d9d7a4bf08..1fc6218b3e302 100644 --- a/packages/astro/test/astro-markdown-plugins.test.js +++ b/packages/astro/test/astro-markdown-plugins.test.js @@ -68,20 +68,20 @@ describe('Astro Markdown plugins', () => { expect($('#github-flavored-markdown-test').hasClass('title')).to.equal(true); }); - for (const githubFlavoredMarkdown of [true, false]) { - it(`Handles GFM when githubFlavoredMarkdown = ${githubFlavoredMarkdown}`, async () => { + for (const gfm of [true, false]) { + it(`Handles GFM when gfm = ${gfm}`, async () => { const fixture = await buildFixture({ markdown: { remarkPlugins: [remarkExamplePlugin], rehypePlugins: [[addClasses, { 'h1,h2,h3': 'title' }]], - githubFlavoredMarkdown, + gfm, }, }); const html = await fixture.readFile('/with-gfm/index.html'); const $ = cheerio.load(html); // test 1: GFM autolink applied correctly - if (githubFlavoredMarkdown === true) { + if (gfm === true) { expect($('a[href="https://example.com"]')).to.have.lengthOf(1); } else { expect($('a[href="https://example.com"]')).to.have.lengthOf(0); diff --git a/packages/integrations/mdx/README.md b/packages/integrations/mdx/README.md index 75c7f8a827c76..8267d80de1afb 100644 --- a/packages/integrations/mdx/README.md +++ b/packages/integrations/mdx/README.md @@ -107,7 +107,7 @@ export default defineConfig({ remarkPlugins: [remarkToc], rehypePlugins: [rehypeMinifyHtml], remarkRehype: { footnoteLabel: 'Footnotes' }, - githubFlavoredMarkdown: false, + gfm: false, }) ] }) @@ -137,7 +137,7 @@ export default defineConfig({ markdown: { syntaxHighlight: 'prism', remarkPlugins: [remarkPlugin1], - githubFlavoredMarkdown: true, + gfm: true, }, integrations: [ mdx({ @@ -146,8 +146,8 @@ export default defineConfig({ // Markdown `remarkPlugins` ignored, // only `remarkPlugin2` applied. remarkPlugins: [remarkPlugin2], - // `githubFlavoredMarkdown` overridden to `false` - githubFlavoredMarkdown: false, + // `gfm` overridden to `false` + gfm: false, }) ] }); diff --git a/packages/integrations/mdx/src/index.ts b/packages/integrations/mdx/src/index.ts index 070a614813cae..7213ca916b5eb 100644 --- a/packages/integrations/mdx/src/index.ts +++ b/packages/integrations/mdx/src/index.ts @@ -188,7 +188,7 @@ function applyDefaultOptions({ extendMarkdownConfig: options.extendMarkdownConfig ?? defaults.extendMarkdownConfig, recmaPlugins: options.recmaPlugins ?? defaults.recmaPlugins, remarkRehype: options.remarkRehype ?? defaults.remarkRehype, - githubFlavoredMarkdown: options.githubFlavoredMarkdown ?? defaults.githubFlavoredMarkdown, + gfm: options.gfm ?? defaults.gfm, remarkPlugins: options.remarkPlugins ?? defaults.remarkPlugins, rehypePlugins: options.rehypePlugins ?? defaults.rehypePlugins, shikiConfig: options.shikiConfig ?? defaults.shikiConfig, diff --git a/packages/integrations/mdx/src/plugins.ts b/packages/integrations/mdx/src/plugins.ts index 0714fdde9053c..6d38f8d06cba2 100644 --- a/packages/integrations/mdx/src/plugins.ts +++ b/packages/integrations/mdx/src/plugins.ts @@ -157,7 +157,7 @@ export async function getRemarkPlugins( if (mdxOptions.syntaxHighlight === 'prism') { remarkPlugins.push(remarkPrism); } - if (mdxOptions.githubFlavoredMarkdown) { + if (mdxOptions.gfm) { remarkPlugins.push(remarkGfm); } diff --git a/packages/integrations/mdx/test/mdx-plugins.test.js b/packages/integrations/mdx/test/mdx-plugins.test.js index 6d1ff687a1e31..f74ded3ea64e4 100644 --- a/packages/integrations/mdx/test/mdx-plugins.test.js +++ b/packages/integrations/mdx/test/mdx-plugins.test.js @@ -87,7 +87,7 @@ describe('MDX plugins', () => { fixture = await buildFixture({ markdown: { remarkPlugins: [remarkToc], - githubFlavoredMarkdown: false, + gfm: false, }, integrations: [ mdx({ @@ -119,20 +119,14 @@ describe('MDX plugins', () => { ).to.be.null; }); - it('Handles githubFlavoredMarkdown', async () => { + it('Handles gfm', async () => { const html = await fixture.readFile(FILE); const { document } = parseHTML(html); if (extendMarkdownConfig === true) { - expect( - selectGfmLink(document), - 'Does not respect `markdown.githubFlavoredMarkdown` option.' - ).to.be.null; + expect(selectGfmLink(document), 'Does not respect `markdown.gfm` option.').to.be.null; } else { - expect( - selectGfmLink(document), - 'Respects `markdown.githubFlavoredMarkdown` unexpectedly.' - ).to.not.be.null; + expect(selectGfmLink(document), 'Respects `markdown.gfm` unexpectedly.').to.not.be.null; } }); }); diff --git a/packages/markdown/remark/src/index.ts b/packages/markdown/remark/src/index.ts index 4b0304f04e97a..c4ba677ab3e98 100644 --- a/packages/markdown/remark/src/index.ts +++ b/packages/markdown/remark/src/index.ts @@ -42,7 +42,7 @@ export const markdownConfigDefaults: Omit, 'draft remarkPlugins: [], rehypePlugins: [], remarkRehype: {}, - githubFlavoredMarkdown: true, + gfm: true, }; /** Shared utility for rendering markdown */ @@ -57,7 +57,7 @@ export async function renderMarkdown( remarkPlugins = markdownConfigDefaults.remarkPlugins, rehypePlugins = markdownConfigDefaults.rehypePlugins, remarkRehype = markdownConfigDefaults.remarkRehype, - githubFlavoredMarkdown = markdownConfigDefaults.githubFlavoredMarkdown, + gfm = markdownConfigDefaults.gfm, isAstroFlavoredMd = false, isExperimentalContentCollections = false, contentDir, @@ -70,7 +70,7 @@ export async function renderMarkdown( .use(remarkInitializeAstroData) .use(isAstroFlavoredMd ? [remarkMdxish, remarkMarkAndUnravel, remarkUnwrap, remarkEscape] : []); - if (githubFlavoredMarkdown) { + if (gfm) { parser.use(remarkGfm); } diff --git a/packages/markdown/remark/src/types.ts b/packages/markdown/remark/src/types.ts index e224ffa620098..5940e4a4ef7d5 100644 --- a/packages/markdown/remark/src/types.ts +++ b/packages/markdown/remark/src/types.ts @@ -43,7 +43,7 @@ export interface AstroMarkdownOptions { remarkPlugins?: RemarkPlugins; rehypePlugins?: RehypePlugins; remarkRehype?: RemarkRehype; - githubFlavoredMarkdown?: boolean; + gfm?: boolean; } export interface MarkdownRenderingOptions extends AstroMarkdownOptions {