11 KiB

Raw Blame History

outline
deep

Pesquisa

Pesquisa Local

VitePress oferece suporte à pesquisa de texto completa usando um índice no navegador graças ao minisearch. Para habilitar esse recurso, basta definir a opção themeConfig.search.provider como 'local' no arquivo .vitepress/config.ts:

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local'
    }
  }
})

Exemplo de resultado:

Alternativamente, você pode usar Algolia DocSearch ou alguns plugins da comunidade como https://www.npmjs.com/package/vitepress-plugin-search ou https://www.npmjs.com/package/vitepress-plugin-pagefind.

i18n

Você pode usar uma configuração como esta para usar a pesquisa multilínguas:

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        locales: {
          zh: {
            translations: {
              button: {
                buttonText: '搜索文档',
                buttonAriaLabel: '搜索文档'
              },
              modal: {
                noResultsText: '无法找到相关结果',
                resetButtonTitle: '清除查询条件',
                footer: {
                  selectText: '选择',
                  navigateText: '切换'
                }
              }
            }
          }
        }
      }
    }
  }
})

Opções MiniSearch

Você pode configurar o MiniSearch assim:

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        miniSearch: {
          /**
           * @type {Pick<import('minisearch').Options, 'extractField' | 'tokenize' | 'processTerm'>}
           */
          options: {
            /* ... */
          },
          /**
           * @type {import('minisearch').SearchOptions}
           * @default
           * { fuzzy: 0.2, prefix: true, boost: { title: 4, text: 2, titles: 1 } }
           */
          searchOptions: {
            /* ... */
          }
        }
      }
    }
  }
})

Saiba mais na documentação do MiniSearch.

Apresentador de Conteúdo Personalizado

Você pode personalizar a função usada para apresentar o conteúdo markdown antes de indexá-lo:

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        /**
         * @param {string} src
         * @param {import('vitepress').MarkdownEnv} env
         * @param {import('markdown-it')} md
         */
        _render(src, env, md) {
          // retorne a string HTML
        }
      }
    }
  }
})

Essa função será removida dos dados do site no lado do cliente, então você pode usar APIs do Node.js nela.

Exemplo: Excluindo páginas da pesquisa

Você pode excluir páginas da pesquisa adicionando search: false ao frontmatter da página. Alternativamente:

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        _render(src, env, md) {
          const html = md.render(src, env)
          if (env.frontmatter?.search === false) return ''
          if (env.relativePath.startsWith('algum/caminho')) return ''
          return html
        }
      }
    }
  }
})

::: warning Nota No caso uma função _render personalizada ser fornecida, você precisa manipular o search: false do frontmatter por conta própria. Além disso, o objeto env não estará completamente populado antes que md.render seja chamado, então verificações em propriedades opcionais env, como frontmatter, devem ser feitas após isso. :::

Exemplo: Transformando conteúdo - adicionando âncoras

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        _render(src, env, md) {
          const html = md.render(src, env)
          if (env.frontmatter?.title)
            return md.render(`# ${env.frontmatter.title}`) + html
          return html
        }
      }
    }
  }
})

Pesquisa Algolia

VitePress oferece suporte à pesquisa em seu site de documentação usando Algolia DocSearch. Consulte o guia de início deles. Em seu arquivo .vitepress/config.ts, você precisará fornecer pelo menos o seguinte para que funcione:

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: '...',
        apiKey: '...',
        indexName: '...'
      }
    }
  }
})

i18n {#algolia-search-i18n}