How to customize markdown with Astro components ?

[wassfila]

motivation

• the web has plenty of ways how to generate html
• Astro has a revolutionary language and compiler to generate html
• Markdown is a main component of the JAM stack revolution
• Astro has SSG as it's leading and differenciating feature
• Markdown is a first class citizen in Astro (out of the box experience reaches a huge community)
• is it possible to customize a markdown component with an .astro component ? no
• when people ask about how to enhance md headings, we need to referr to the classic rehype toolchain (total disconnection from Astro experience)

md vs mdx

md import pipeline renders to html, mdx import pipeline renders to .js/.ts/.jsx... which allows to customize html tags with Astro components.

goal

I would like to take advantage of an mdx similar power in .md files with Astro, I do nof need mdx with .md extension rather md components enhancements like in mdx

non goal

I do not want to treat mdx with .md extension which has a separate discussion #503

examples

I would like to avoid

• (-) embedding svg assets in config files to e.g. add link icons in headings elements (example https://github.com/withastro/docs/blob/52bf88ec74e3d01d212808d678320f190be64f76/astro.config.ts#L16)

and rather

• (+) allow advanced enhancements written in html like e.g. .astro and NOT in rehype js format. (example just for reference in mdx not md https://github.com/MicroWebStacks/astro-big-doc/blob/9d4215e86c020bf72f28ce83d8e494df23e0ff7d/src/components/headings/H1.astro#L15)

Any ideas of the finest approach to achieve this, it feels like this last step is missing to unleash Astro's power over Markdow !!!

Markdown and SSR (secondary goal)

Markdown currently does not make sense with SSR given that you need to rebuild and redeploy when the markdown changes.
I wanted to keep this section because it is related to markdown customization, if it is possible to customize html string with astro component then remote markdown support would become easy to fulfill with a generic pipeline.

community posts

the search is really hard, only from recent period

https://discord.com/channels/830184174198718474/1077511972163162182

https://discord.com/channels/830184174198718474/1078754947480424549

https://discord.com/channels/830184174198718474/1075478924420730900

https://discord.com/channels/830184174198718474/1074529716352069693

https://discord.com/channels/830184174198718474/1072255962615926885

https://discord.com/channels/830184174198718474/1056870932305694770

markdown landscape survey and predictions

this is my survey about "markdown" and beyond (light weight markup) landscape
https://github.com/orgs/MicroWebStacks/discussions/8

not only I wish but I will also recommend, help and push towards markdown standardisation and unification of practices. Multiplicity of files extensions is one of them .md, .mdx, .mmd .mdok. I would distinguish flavors and extensions as being website and engine internals and not splitting the content base into heterogeneous incompatible categories nor being used as a lockin opportunity. Therefore I do not see myself deviating from the the .md extension and from a correct minimilastic githug rendering. The rest, styling and augmentations, is the core business of md renderering engines, why would one prevent itself from profiting of its language technology for such enhancements.

references

• astro remote : https://github.com/natemoo-re/astro-remote
• programmatic component creation https://github.com/withastro/astro/blob/main/packages/astro/test/units/render/jsx.test.js#L33-L35
• question on Stack to inspire ideas https://stackoverflow.com/questions/74919230/how-to-customize-markdown-with-astro-components
• Discord discussion : https://discord.com/channels/830184174198718474/1056870932305694770
• Discord related discussion for md layout https://discord.com/channels/830184174198718474/1036728977739489391
• astro remote : https://github.com/natemoo-re/astro-remote
• How would I programatically create an Astro subtree? #378
• https://github.com/withastro/astro/blob/main/packages/astro/test/units/render/jsx.test.js#L33-L35

[stereobooster]

My use-case: I want to write "GFM asides" and render them with the help of Starlight Aside, without need to convert to MDX

e.g. write

> [!NOTE]
> Highlights information that users should take into account, even when skimming.

but it would be generated as it was written as

import { Aside } from "@astrojs/starlight/components";

<Aside>Highlights information that users should take into account, even when skimming.</Aside>

https://astro-digital-garden.stereobooster.com/recipes/gfm-aside/

[tisonkun]

I like this idea.

[wassfila]

for info, I currently used a custom markdown parser and renderer, and I can with it create all sorts of markdown components with Astro, as example, this it the aside component written in astro https://github.com/MicroWebStacks/astro-big-doc/blob/main/src/components/markdown/directive/NotesDirective.astro

[stereobooster]

I tested how overrides work in MDX. Some of components work as expected, like image, link, header. But code is kind of "broken". See https://github.com/stereobooster/astro-customize-markdown

[wassfila]

yeah MDX for me is out of hope, that's why I had to focus on MD, there's nothing I could not do with pure MD, except allowing content creators to inject code, which I do not want.

[jfkonecn]

I have the same use case. It’s not quite what you're looking for, but I ended up using web components in my markdown as a work around.