Markdown Enhancements

[lorenzolewis]

Background

I absolutely love the functionality and direction that the Content Collections RFC guides Astro towards. It's a lot of really good baseline work that will hopefully help those integrating content that might not be written alongside an Astro project.

That being said, there can be a lot of friction to a develop new to Astro coming from another platform where they're expecting enhanced markdown functionality out of the box. These can often times be fixed by changing the format of the Markdown, but those are often seen as workarounds and may not be possible to do (such as when a developer's Markdown content is being rendered to another service in parallel and they don't have the flexility to change it).

Current Behaviour

There are already some defaults applied to all markdown parsed by Astro: https://docs.astro.build/en/guides/markdown-content/#configuring-markdown-and-mdx

Missing Behaviour

The below list contains functionality that I'm personally missing. I'm sure there are a lot more and that some are more relevant than others.

• Assets relative to Markdown files ([Proposal] Resolve relative assets on Markdown files #334, Relative links RFC #381, and [Draft] Relative path handling in Astro #23 all touch on this as well as the various issues referenced within them)
• Link handling and resolution between Markdown files (.md included in href for markdown links astro#5682 and Link Resolution in index.md files astro#5680)
• Mermaid diagram support (Markdown mermaid support #267)
• Internal broken link detection (and ability to error during build) similar to https://docusaurus.io/docs/api/docusaurus-config#onBrokenMarkdownLinks
• readme.md being used as an index page
• Extract classes from image references to support use cases such as GitHub-style themed images
• Note admonitions for quote blocks in the style of [Markdown] An option to highlight a "Note" and "Warning" using blockquote (Beta) community/community#16925

Not all of these may make sense and by introducing more it opens up a can of worms for a potential flood of "well just add xyz feature" for the way Astro parses Markdown.

Current Solutions

Right now you can add in your own remark and rehype plugins as outlined in https://docs.astro.build/en/guides/markdown-content/#markdown-plugins. This can be a daunting task for those who might not be familiar with these tools (how many times did I have to look up the difference between what remark and rehype do today because I kept forgetting? 😅).

There is a very large plugin ecosystem for remark and rehype, but again it can get daunting knowing which plugin to use, how it affects the rendered content, and exposes a whole new level of complexity to a developer. This can cause a lot of DX friction for those moving from another platform where they're used to some of these things happening by default (moving from Docusaurus in my case).

Proposed Solutions

1. Add opt-in behaviour for "enhanced" markdown parsing/rendering as a universal Astro config
2. Add opt-in behaviour per Content Collection to selectively turn this on per collection
3. Curate a list of community- and/or Astro-maintained remark/rehype plugins that map to common use cases someone might expected when coming from another platform

I'd personally prefer either option 1 or 2. It would reduce the friction of developers coming from another platform where they're used to these niceties. This can be a set of "blessed" functionality that I can count on working in Astro and not have to worry about community plugins, updating additional dependencies, wondering how they all interact with each other, etc.

---

Hopefully there's more feedback on this as I'd love to get the perspective of those in the community who have been around longer than I have; I'd love to hear their feedback!

Oh, and thanks for the amazing Astro project <3

[lorenzolewis]

One option that comes to mind around what the configuration would look like is inspired by withastro/astro#5684.

There could an enum in the config that contains these values:

• none: Astro does no processing with the markdown files
• basic: (default) Astro does processing like it does today (with GitHub Flavoured Markdown, code highlight, heading ID generation)
• enhanced: This could cover the cases mentioned in the original discussion post (at least the ones chosen to include).

This would also bake in the functionality where a user really doesn't want Astro to do any processing on their files.

[delucis]

Interesting ideas here! And quite a few of your “Missing Behaviour” list are things we needed to build custom solutions for for the Astro Docs site, so would definitely be interesting to think about generalizing those.

Pretty much all of these exist in the remark/rehype plugin space, so I wonder if this can be an integration — even potentially a userland experiment initially — rather than built in.

How exactly a user opts in/out of things is also something to resolve. While the none/basic/enhanced is simple to get started, it falls apart once a user says “Love enhanced but how do I disable feature X?” (This is kind of the issue we have today with Astro’s defaults.) But that can be tackled later.

[lorenzolewis]

It could be that none | basic | enhanced are communicated as a collection of plugins that help someone get the general functionality they want. But then if we wanted to give more granular abilities to tweak them then you use the remarkPlugins config for that (to either replace or extend the current plugins.

I'm probably going to build these out in the tauri.app rewrite we're doing in Astro and plan to keep each plugin separate. If we want to continue down this then could look at pulling them upstream directly into Astro.

Like you said, a lot of these already exist in the plugin space, but I think there could be a benefit to bundling/redistributing them with Astro for the sake of a user not having to dig into that ecosystem if they choose not to.

[bholmesdev]

I agree with your point there @delucis. Admittedly, I'm not comfortable using blanket terms for "basic" and "enhanced," as it's fairly opaque what is applied under each setting. I also don't think a simplified enum allows enough inversion of control to pick-and-choose presets you need. I think the target demographic for "enhanced" users aren't those that just want more features; they usually need a preset of options suited to their use case, like "enhanced for blogs" or "enhanced for docs."

To solve this, I could imagine each of these being "preset" objects rather than string values. You can either apply outright or choose properties individually:

import { basic, enhanced } from '@astrojs/markdown-remark/presets';

markdown: {
  // 1. Apply preset untouched
  preset: enhanced,
  // 2. Choose pieces you need
  preset: {
    blockquotes: enhanced.blockquotes,
  }
}

This is definitely doable from an Astro integration today though! I'd love to see user feedback on that.

[lorenzolewis]

I like the code example @bholmesdev.

Another options is that maybe basic and enhanced are just a re-exported array of plugins. Then you could use them like this:

import { enhancedPreset, blockquotes } from '@astrojs/markdown-remark';

markdown: {
  // a. Use a preset by spreading it
  plugins: {[
    ...enhancedPreset
  ]},
  // b. or cherry pick the specific ones you would like
  plugins: {[
    blockquotes
  ]}
}

This leaves out the distinction between remark vs rehype plugins of course, but gets the general idea across.

[delucis]

Yeah, I think the tricky bit is actually handling what’s remark and what’s rehype if you’re relying on folks using this directly inside the different re____Plugins arrays. Making this an integration can help solve for that if you’re comfortable with hiding the logic a bit: use an object like in Ben’s sketch and the integration decides behind the scenes what ends up in which plugins array.

[jonsage]

Just adding a couple of cents.

With regard to link resolution of .md files, my preferred behaviour would be that if I have relative (or absolute) links to files in the static source, then those links would magically be transformed to continue working in the output HTML.

I would think Astro knows the original file paths of all files, so it could be some functionality, probably hooked into reMark plugins but with config from Astro, that when processing links, checks them against the graph and grabs the permalink of each and swaps that in.

It's probably not straightforward, but it means markdown authored to work on github or in vscode or other tools could be built to html and continue working - otherwise it means links will be broken in one side or the other.

Jekyll has a plugin for such functionality with an explanation behind it's reasoning:

https://github.com/benbalter/jekyll-relative-links

I would like to see this as an option. The purist in me desires the simplicity of a folder of inter-linked markdown files that can be browsed as source (excellent for docs sites where people can browse in GitHub) as well has transformed into a beautiful butterfly website.

[vernak2539]

In regards to the "resolving relative assets" part, I've built a rehype plugin to satisfy my want to link between markdown/mdx files to other markdown/mdx files using relative paths. It can be found on Github and NPM.

Hopefully it can serve as a stopgap until the functionality is decided to be put into Astro (or can be used as a user-land thing if not).

[shishkin]

I think the issue is that content collections rely on a dynamic route to be rendered. So the dynamic page needs to use URL params to lookup the item in the content collection and render it. This function can be arbitrary and thus is not generally reversible. And the relative link resolver needs to go the other way around from a local relative file to URL params. But it should definitely work for static routing of MD pages.

[bholmesdev]

@vernak2539 Exactly right! You'll use dynamic routes to map content collections, or you can store in src/pages/ directory. The latter approach lets you do magical route generation for relative .md paths if this is what you prefer. Though in practice, we prefer explicit dynamic routes to make route generation clear. This is admittedly why we've ruled out relative .md path resolution for the time being 🤷

[vernak2539]

That makes a lot more sense now. I've updated my package with all of the assumptions I made prior to this thread. Will very much look forward to anything else that comes out about relative linking inside markdown content (aside from assets). Thanks again!

[bholmesdev]

Love these discussions! I'll take a look at the plugin to see what Astro could learn from ❤️

[stereobooster]

2¢ to this discussion. Portable markdown links are supported by: Github, VSCode, Hugo, Docusaurus, Obsidian. It would be nice if Astro can support it.