Docs: more information when using a custom theme

[VividLemon]

Is your feature request related to a problem? Please describe.

It can be difficult to gather some "necessary" information when using a fully custom theme. This is normally not much of an issue, but I have found a few issues with the default behavior when using a custom theme.

1. Codeblocks render in a strange way, and it's not very straightforward on how to edit the default behavior.

For example, I frequently make a basic example like so:

\```bash
pnpm add bootstrap bootstrap-vue-next @bootstrap-vue-next/nuxt -D
\```

The code highlighting works well, but I end up getting some weird extra business:

In addition to this, 'code-groups' give undesirable behavior:

::: code-group

\```bash [PNPM]
pnpm add bootstrap bootstrap-vue-next

pnpm add unplugin-vue-components -D
\```

\```bash [YARN]
yarn add bootstrap bootstrap-vue-next

yarn add unplugin-vue-components -D
\```

\```bash [NPM]
npm i bootstrap bootstrap-vue-next

npm i unplugin-vue-components -D
\```

:::

In this specific instance, I solved it by simply not using the default code-group and instead just using my already existing custom component

<b-tabs v-model="codePreference">
  <b-tab title="PNPM">

\```bash
pnpm add bootstrap bootstrap-vue-next
\```

  </b-tab>
  <b-tab title="YARN">

etc etc.

However, each of these instances still render

Above them, which is undesirable

2. Links,

The default behavior of links is "fine", however, it would be nice if I could convert all links in markdown to use a component of my choosing. Specifically, I already have a "BLink" component that I could use.

In addition to this, a nice ease of use that I would enjoy is the auto creation of perma links. This one also goes together with the next section. Simply using ## Some header, it would be nice if it auto created subsequent links for each instance... However, it doesn't. Which, perhaps most people wouldn't benefit from that behavior. This goes with Table of contents as I'm not exactly sure how a toc would be generated without these items existing... Perhaps you need to make each of these things manually? But if that's the case, how do custom themes like the default theme do it? There has to be a way if the default theme accomplishes this behavior.

3. Table of contents

Now, I haven't used the table of contents list, but I imagine that this one will be somewhat difficult as there's little information on it's usage. It's only shown usage is [[toc]]. But this doesn't really give much. Say for example if you wanted to put the toc into a layout vue component. It doesn't say anything about that.

4. Custom containers

Now, a simple solution to using a "custom container" is to use your own component. However, I'm wondering if there is another way to fulfill this syntax:

::: info
Foo!
:::

And simply have it use a component of your choosing.

Describe the solution you'd like

Perhaps some more information on the "Using a Custom Theme" section could be useful. Most of the issue I find here revolve around the "Markdown Extensions" usage. It's clear that extensions are available whether or not you decide to use a custom theme, so it makes it difficult to understand how to overwrite some of those behaviors.

Describe alternatives you've considered

Honestly, I'm not sure of the best alternatives in any of these situations. In some cases, I can simply use my builtin components and forgo the extensions.

Additional context

It seems that some of this information is upstream in the markdown-it library. But this I am unsure about. But in addition to this, there is the theme/index.ts file, which proposes to export a weakly typed object. Perhaps there could be a strongly typed function for this that would provide some info

I have found no reference to this being strongly typed though.

Validations

• Follow our Code of Conduct
• Read the docs.
• Read the Contributing Guidelines.
• Check that there isn't already an issue that asks for the same feature to avoid creating a duplicate.

[SimonEast]

This sounds like some good feedback. There are also some areas of the docs I would like to see expanded. I've already submitted a PR for some improvements, although it does not specifically cover the issues you've raised. Still waiting to see if it's accepted.

But to touch on a few points:

1. Code blocks — have you looked at some of the CSS for the default code block components? Maybe there is some CSS there that you might need to apply to your own theme if not using the default one.

2. Links — the default theme does seem to generate links to each subheading. Are you saying this doesn't happen when building a custom theme?

I'm not familiar enough with the other topics to comment on those.

[brc-dd]

Most of this I believe was covered already in our discussion on Discord at that time. Still just putting it here:

1. You need to add css for those to show properly. You can refer our source code for that.
2. This should already be happening. For links, you can override them via markdown config.
3. [[toc]] is only for markdown-use. You need to manually traverse all headings to generate an outline. Alternatively, you can enable headers options in markdown config and use them from useData()
4. Can be added using markdown-it-container.