psyche

? psique

Psyche é uma solução de queda para a documentação de pesquisa, inspirada no DocSearch da Algolia.

• Parece e é incrível de usar.
• A pesquisa é rápida, precisa e digitada por digitação .
• Pode ser incluído em qualquer site de documentação estática ou gerada por servidor .
• Ele funciona como um sitemap sitemon-navigável do teclado .
• Ele simplifica o registro de teclas de atalho dependente de plataforma em todo o local .
• É amigável para dispositivos móveis .
• Ele suporta modos claros e escuros .

Confira a documentação da noção-aprimoramento de uma demonstração ao vivo.

AVISO: Psyche é construído especificamente para pesquisar documentação. Ele não é criado para implementação em outras interfaces (por exemplo, comércio eletrônico) ou usar com esquemas de dados personalizados.

Começando

Gerando um índice

O cliente Psyche requer um índice pré-gerado de resultados para pesquisar. Esta deve ser uma variedade de registros de Result (consulte Types.D.Ts). Os índices são fornecidos ao cliente programaticamente, mas devem assumir a forma de um arquivo .json não formatado/minificado.

Os indexadores são plug-ins/middleware que rastreiam um site e geram um índice, durante um processo de construção ou na fly se o site for servido dinamicamente.

Os indexadores para alguns geradores de documentação são fornecidos abaixo. Se o seu gerador de escolha ainda não for suportado, abra uma solicitação de recurso ou escreva o seu próprio e abra uma solicitação de tração.

Lume

Adicione o seguinte ao seu arquivo _config.ts :

 import psyche from 'https://deno.land/x/psyche/indexers/lume.ts' ;

site . use ( psyche ( ) ) ;

O indexador pode ser configurado fornecendo um objeto LumeConfig como o primeiro argumento da chamada psyche() (consulte Types.D.Ts).

Por padrão:

• O índice será emitido para /search.json .
• Páginas sem data.section ou onde data.draft = true serão ignoradas.
• As páginas serão agrupadas por data.section_order e classificada por data.order .
• Os títulos da página são acessados ​​a partir de data.title .
• As seções da página são acessadas a partir de data.section .
• Chefos, blocos de código, parágrafos e listas dentro de um elemento <article></article> em uma página são indexados de acordo com o HTML semântico. Outros elementos (por exemplo, <blockquote></blockquote> ) são tratados como parágrafos. Isso funciona melhor com a saída de marcação.

Leia os dados da página e/ou as páginas de dados compartilhadas da documentação de Lume para ver como definir essas propriedades.

Incluindo o cliente

O cliente Psyche está escrito no TypeScript. Você pode importá-lo diretamente se os ativos do seu site forem agregados por por exemplo, ou importar a compilação JavaScript pré-transpiliada e minificada.

 import psyche from 'https://deno.land/x/psyche/client/mod.ts' ;
// or
import psyche from 'https://deno.land/x/psyche/client/psyche.min.mjs' ;

A exportação padrão psyche é uma função que, quando fornecida com um objeto ClientConfig (consulte Types.D.Ts) retornará um ClientInstance (consulte types.d.ts).

Chamar .register() em uma instância do cliente inserirá o componente no documento e ouça as prensas de tecla de atalho. O componente pode ser aberto chamando .open() ou pressionando CTRL/⌘ + K

Por exemplo

 const searchInstance = psyche ( {
  theme : { scrollbarStyle : 'square' } ,
  index : await fetch ( '/search.json' ) . then ( ( res ) => res . json ( ) ) ,
} ) ;
searchInstance . register ( ) ;
searchInstance . open ( ) ; 

Registrando teclas de atalho

Para adicionar uma tecla de atalho à lista no modal de pesquisa, adicione -a à matriz hotkeys do objeto ClientConfig da Psyche (consulte types.d.ts).

Para teclas de atalho dependentes da plataforma, o platformModifier de exportação nomeado será equivalente à chave ⌘ no macOS ou à chave CTRL em outras plataformas.

Para lidar com as teclas de atendimento, forneça um objeto ClientHotkey (consulte Type.D.Ts) para o Nomeado Export registerHotkey . Este é um KeyboardEvent parcial com algumas propriedades adicionais:

• A propriedade platformModifier é equivalente a metaKey no MacOS ou ctrlKey em outras plataformas.
• A propriedade onkeydown será chamada quando a combinação de teclas for pressionada, passou o KeyboardEvent desencadeado como seu primeiro argumento.
• A propriedade onkeyup será chamada quando a combinação de chave for lançada, passou o KeyboardEvent desencadeado como seu primeiro argumento.

Por exemplo

 import psyche , {
  registerHotkey ,
  platformModifier ,
} from 'https://deno.land/x/psyche/client/psyche.min.mjs' ;

registerHotkey ( {
  key : 'l' ,
  platformModifier : true ,
  shiftKey : true ,
  onkeydown : ( event ) => {
    event . preventDefault ( ) ;
    toggleTheme ( ) ;
  } ,
} ) ;

const searchInstance = psyche ( {
  hotkeys : [ { kbd : ` ${ platformModifier } + SHIFT + L` , label : 'to toggle theme' } ] ,
} ) ;
searchInstance . register ( ) ;

---

As alterações neste projeto são registradas no Changelog.

Este projeto está licenciado sob a licença do MIT.

Para apoiar o desenvolvimento futuro deste projeto, considere patrocinar o autor.