feat!: allow customizing markdown renderer used for local search indexing

[damieng]

Localsearch indexes content directly rendered from the file system without opportunity to change the HTML before indexing.

This can be a problem if your layout normally adds important elements such as a <h1> based on a Frontmatter title (as the VueJS blog does).

This PR introduces a hook where, for localsearch, you can provide a function that takes the HTML, environmental data such as the page path and Frontmatter, and a render function. You can then use these elements to either re-process the markdown or to manipulate it in some way.,

In the VueJS blog scenario you can now do this to ensure titles are headings on your search results:

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      options: {
        preIndexRender: (html, env, render) =>
          env.frontmatter?.title
            ? render('# ' + env.frontmatter?.title) + html
            : html
      }
    }
  }
}

Thanks for your consideration!

[damieng]

Removed "fileContents" as the raw markdown is available as env.content.

[brc-dd]

Hi, sorry for the delay. But this might need some more consideration as preIndexRender will be a node only API and having it serialized in each page won't make sense. We'll need some way to mark it so that it doesn't appear in the client-side code. I'll take a look. Thanks for the PR.

[damieng]

No problem, thanks for the update. Let me know if there is anything I can help with.

[brc-dd]

I think we probably can decide on some name conventions like node_<fnName> and strip them away in serializer. These functions need not be pure.

The other alternative I see is using some property to indicate node only: name: { node: true, fn: () => {...} } But that's more verbose.

Other thing I tried was using some magic comments, but turns out esbuild removes them while loading the config, so those won't work.

First should be good IMO, wdyt?

[damieng]

The node_ prefix works for me. I've updated the PR and re-tested it on my project and it works fine.

[brc-dd]

Thanks for the update. I'll update the serializer part.

[brc-dd]

Can you verify if the example mentioned in https://deploy-preview-2770--vitepress-docs.netlify.app/reference/default-theme-search#example-transforming-content-adding-anchors works for you with the latest commit?

[damieng]

Confirmed working, my H1-adding scenario is now:

  themeConfig: {
    search: {
      provider: "local",
      options: {
        detailedView: true,
        _render: (src, env, md) => {
          const html = md.render(src, env)
          if (env.frontmatter?.search === false) return ""
          return env.frontmatter?.title ? md.render("# " + env.frontmatter?.title) + html : html
        },
      },
    },

Thanks!