Nossa jornada para construir um índice pesquisável com Algolia e NodeJS

Juntei-me ao engenheiro de pilha completa da Starschema, Soma Osvay, para escrever sobre um projeto próximo e querido ao meu coração: a documentação do desenvolvedor. Soma e eu esperamos que você goste deste artigo, onde abordamos o caso de uso, os desafios e a implementação que Soma criou.

Aqui na Starschema, temos muitos projetos que fizemos como parte de uma consulta à documentação de remarcação . Quando damos suporte a essas soluções existentes ou queremos desenvolver um novo projeto, muitas vezes queremos pesquisar toda a documentação. No momento, não temos uma solução, o que nos custa horas de trabalho, pois temos que fazer esse trabalho manualmente.

Caso de uso

Precisamos ser capazes de pesquisar projetos relacionados a tópicos específicos para verificar detalhes de implementação, obter ideias do código e muito mais. A equipe de vendas também precisa de uma solução para determinar que tipo de projetos nossa equipe concluiu para determinados tópicos e poder comunicá-los rapidamente a clientes em potencial.

Também seria ótimo ter algo como um estouro de pilha interno para nossos desenvolvedores, já que estamos fazendo muito trabalho técnico profundo no Tableau. Os gerentes de projeto também precisam ser capazes de determinar quais funcionários trabalharam com determinadas tecnologias para que possam obter respostas rápidas e fáceis.

Em suma, precisamos ser capazes de buscar nossos próprios projetos com base nos seguintes atributos:

1. Tecnologias utilizadas (linguagens de codificação, bases de dados, etc.)
2. Palavras-chave do projeto (tags)
3. A própria documentação do projeto, como instruções de instalação, documentação técnica, etc.
4. Prazo de quando o projeto ocorreu

Todos esses atributos existem nos arquivos de markdown da documentação interna – só precisamos de uma maneira de pesquisá-los.

Plano de implementação

O plano é usar uma CLI do NodeJS como uma prova de conceito que irá:

1. Raspe os principais repositórios públicos do GitHub e pegue o arquivo de marcação README (que representará nossos projetos internos)
2. Armazena os arquivos de documentação no Algolia juntamente com as informações básicas do projeto (título, linguagem(s) de programação, tags, etc)

A CLI conterá log avançado e argumentos de linha de comando para facilidade de uso. Também queremos hospedá-lo na web para que as pessoas possam experimentá-lo.

Desafio

O maior desafio é o tamanho do registro — Algolia só permite que nossos registros tenham no máximo 100 KB. No entanto, a maioria dos arquivos de documentação de remarcação são muito maiores. A solução é que precisamos dividir os arquivos markdown em várias partes dentro do Index. Também precisamos garantir que, quando procuramos algo, um único projeto apareça apenas uma vez - mesmo que esteja dividido em vários registros.

Felizmente, o Algolia tem um recurso distinto para que possamos desduplicar esses resultados com muita facilidade.

Implementação do indexador

Para tornar o uso do Indexador o mais fácil possível, optei por criar uma CLI para ele conforme mencionado acima. Depois de fornecer os argumentos necessários, a ferramenta inicializará automaticamente o repositório, removerá todos os registros existentes e definirá as configurações de relevância.

O poder da ferramenta é uma API direta do GitHub que obtém o número solicitado dos principais repositórios, extrai todos os seus metadados e baixa o arquivo README. Ele também filtrará os repositórios que não possuem um proprietário ou um arquivo README, fornecendo os melhores resultados. Por fim, ele também converterá o conteúdo de markdown em HTML para facilitar a renderização no front-end.

Para manter o tamanho do registro sob controle, a ferramenta dividirá automaticamente os READMEs com mais de 50 mil caracteres em registros adicionais. Dessa forma, os registros não ficarão muito grandes, mas um registro ainda deve atender a quase todos os repositórios. Em seguida, ele sincronizará essas informações com 100 registros do Algolia por vez, para que possamos atender às recomendações de lote conforme descrito aqui na documentação.

Implementação de front-end

Para servir como ponto de partida, aproveitei a biblioteca create-instantsearch-app lançada pela Algolia e lancei um clichê InstantSearch.js. A partir daqui, pude adicionar widgets adicionais fornecidos pelo InstantSearch.js, como a paginação e o seletor de tamanho de página, que funcionaram muito bem.

Como também coletamos metadados do repositório com o markdown, também precisamos customizar o componente de hits para incluir essas informações adicionais. Freqüentemente, os metadados são tão importantes quanto a descrição da biblioteca, para que os desenvolvedores possam ver rapidamente se é uma biblioteca popular, quem a lançou, as tags e muito mais. Também adicionei facetas para que os usuários pudessem filtrar pela linguagem de programação, tags ou quantas vezes ele foi bifurcado.

A peça final do quebra-cabeça foi adicionar o botão 'Abrir documentação', permitindo que você leia rápida e facilmente o conteúdo de markdown do repositório em um pop-up sem sair do aplicativo. Se o registro no qual estamos clicando tiver várias linhas, ele carregará automaticamente os registros adicionais e os concatenará na tela — incrível!

Conclusão

Este projeto foi um teste divertido e realmente me mostrou como o Algolia é flexível para diferentes casos de uso como o nosso. Os widgets prontos para usar me pouparam muito tempo durante a prototipagem e ter resultados relevantes desde as primeiras teclas é super impressionante. Também acho que seria superinteressante se pudéssemos aproveitar o poder do Algolia Recommend se pudéssemos gerar eventos suficientes de usuários clicando em projetos internamente.

Você pode ver uma demonstração ao vivo do projeto de teste do GitHub aqui , com um botão que configurará você com as credenciais de demonstração padrão para visualizar nosso índice. Interessado no código de indexação de back-end? Você pode encontrar isso aqui no GitHub!

Também publicado aqui.