The remark config documentation misses some important information

[nibble0101]

📋 Explain your issue

I wanted to add the remarkToc plugin to my astro config as described in the documentation.

export default defineConfig({
  markdown: {
    remarkPlugins: [remarkToc],
  },
});

However, I wanted to customize the remarkToc plugin instead of using the defaults. This information is missing in the docs. I had to first look look up the RemarkPlugins type in the repo before figuring out how to pass in the config object like so:

export default defineConfig({
  markdown: {
    remarkPlugins: [[remarkToc, { ordered: true }]],
  },
});

I think it would be a good idea to explain the different ways of adding the plugins with custom config or linking to that explanation it if it has been explained somewhere else in the docs.

[TheOtterlord]

The markdown guide explains this (see Customizing a plugin. I did notice the reference is presented first in the search results, which I'm guessing is what lead you to reference? We could 100% look at adding a plugin with options or a link to the example.

[nibble0101]

The markdown guide explains this (see Customizing a plugin. I did notice the reference is presented first in the search results, which I'm guessing is what lead you to reference? We could 100% look at adding a plugin with options or a link to the example.

Yes, I ended up in the reference via search. An example plugin with options or a link to the existing example will make things a lot easier.

[sarah11918]

Interestingly when I searched, I did not get reference first but did get the upgrade guides first, then the Learn, and then reference!

What if we just update the example on the configuration reference page, which currently shows remarkToc anyway, and just add any old custom value, e.g. the one on the Markdown page:

remarkPlugins: [ [remarkToc, { heading: "contents"} ] ],

We try to keep the configuration page as concise as possible, but this at least is a visual clue to point people in the right direction without needing a ton of words to clutter the page.

Would be happy if someone would like to make a PR to that effect! The change to make would be on this line