8.9 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-async')} md
         */
        async _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: {
        async _render(src, env, md) {
          const html = await md.renderAsync(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.renderAsync 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: {
        async _render(src, env, md) {
          const html = await md.renderAsync(src, env)
          if (env.frontmatter?.title)
            return await md.renderAsync(`# ${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}

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

Clique para expandir

<<< @/snippets/algolia-i18n.ts

Consulte a documentação oficial da Algolia para saber mais. Para começar rapidamente, você também pode copiar as traduções usadas por este site do nosso repositório no GitHub.

Suporte ao Algolia Ask AI

Se quiser incluir o Ask AI, adicione askAi em options:

options: {
  appId: '...',
  apiKey: '...',
  indexName: '...',
  askAi: { assistantId: 'XXXYYY' }
}

::: warning Nota Caso queira apenas a pesquisa por palavra-chave, omita askAi. :::

Painel Lateral do Ask AI

O DocSearch v4.5+ suporta um painel lateral do Ask AI opcional. Quando habilitado, pode ser aberto com Ctrl/Cmd+I por padrão. A Referência da API do Painel Lateral contém a lista completa de opções.

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: '...',
        apiKey: '...',
        indexName: '...',
        askAi: {
          assistantId: 'XXXYYY',
          sidePanel: {
            // Espelha a API do @docsearch/sidepanel-js SidepanelProps
            panel: {
              variant: 'floating', // ou 'inline'
              side: 'right',
              width: '360px',
              expandedWidth: '580px',
              suggestedQuestions: true
            }
          }
        }
      }
    }
  }
})

Se precisar desabilitar o atalho de teclado, use a opção keyboardShortcuts do painel lateral:

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: '...',
        apiKey: '...',
        indexName: '...',
        askAi: {
          assistantId: 'XXXYYY',
          sidePanel: {
            keyboardShortcuts: {
              'Ctrl/Cmd+I': false
            }
          }
        }
      }
    }
  }
})

Modo (auto / sidePanel / hybrid / modal)

Você pode controlar opcionalmente como o VitePress integra a pesquisa por palavra-chave e o Ask AI:

mode: 'auto' (padrão): infere hybrid quando a pesquisa por palavra-chave está configurada, caso contrário sidePanel quando o painel lateral do Ask AI está configurado.
mode: 'sidePanel': força apenas o painel lateral (oculta o botão de pesquisa por palavra-chave).
mode: 'hybrid': habilita o modal de pesquisa por palavra-chave + painel lateral do Ask AI (requer configuração de pesquisa por palavra-chave).
mode: 'modal': mantém o Ask AI dentro do modal do DocSearch (mesmo se você configurou o painel lateral).

Apenas Ask AI (sem pesquisa por palavra-chave)

Se quiser usar apenas o painel lateral do Ask AI, você pode omitir a configuração de pesquisa por palavra-chave de nível superior e fornecer as credenciais em askAi:

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        mode: 'sidePanel',
        askAi: {
          assistantId: 'XXXYYY',
          appId: '...',
          apiKey: '...',
          indexName: '...',
          sidePanel: true
        }
      }
    }
  }
})

Configuração Crawler

Aqui está um exemplo de configuração baseado na qual este site usa:

<<< @/snippets/algolia-crawler.js

8.9 KiB Raw Blame History