🔎 Algolia 검색을 NextJS 및 마크다운 파일과 어떻게 통합했습니까?

2019년부터 1인 개발자로 SaaS for translation management을 구축하고 있습니다. 처음부터 코드 샘플을 게시하고 다른 프레임워크를 통합하는 방법이나 SimpleLocalize CLI를 사용하여 번역 파일을 업로드하고 다운로드하는 방법을 사람들에게 설명할 수 있는 장소가 필요했습니다. SimpleLocalize documentation에서 Algolia 검색이 작동하는 것을 볼 수 있습니다.



처음에는 GitBook 소프트웨어가 그 당시 빛나고 트렌디했기 때문에 사용하기 시작했습니다. 새로운 것을 시작할 때 모든 단계에서 처음부터 시작하고 싶지 않기 때문에 좋은 조치였습니다. 주요 목표는 고객에게 좋은 품질의 코드와 가치를 제공하는 것입니다. 시간을 절약하기 위해 구매할 수 있는(또는 구매해야 하는) 다른 모든 것입니다.

간단히 말해 몇 달 후 GitBook이 마음에 들지 않았습니다. 내 필요에 맞지 않았고 스타일이 마음에 들지 않았고 링크를 조정하고 수정하는 데 너무 많은 시간을 소비했기 때문입니다. 에. 맞춤형 문서를 사용하기로 결정했고 놀랍게도 모든 것이 순조롭게 진행되었습니다! 유일한 콘서트는 모든 문서화 솔루션에서 사용할 수 있는 우수한 검색 기능이 부족하거나 open-source Docusaurus .

설치

Algolia 검색 구성 요소 및 Algolia 클라이언트 설치

npm install react-instantsearch-dom algoliasearch --save

gray-matter Markdown 파서 및 globby 파일 찾기

npm install gray-matter globby --saveDev

구성

import algoliasearch from 'algoliasearch/lite';
import {connectStateResults, Hits, InstantSearch, SearchBox} from 'react-instantsearch-dom';

const searchClient = algoliasearch(
  'APP_ID',
  'SEARCH_API_KEY'
);

결과 구성 요소

기본적으로 Algolia<Hits/> 구성 요소는 검색 쿼리가 비어 있을 때 모든 결과를 표시합니다. 결과가 있고 데이터가 로드된 경우에만 결과가 표시되도록 코드를 조정했습니다.

const Results = connectStateResults(({searchState, searchResults, searching}) => {
  const hasQuery = searchState && searchState.query;
  const hasResults = (searchResults?.hits ?? []).length > 0;
  const isSearching = searching;
  if (hasQuery && hasResults) {
    return <Hits hitComponent={Hit}/>;
  }
  if (hasQuery && !hasResults && !isSearching) {
    return <div>No results 😔</div>
  }
  return null;
}
);

적중 구성 요소

적중 구성 요소는 하나의 검색 결과일 뿐입니다. 복사-붙여넣기가 더 쉽도록 스타일을 제거했습니다. 😄

import React from "react";

function Hit(props: any) {
  const content = props?.hit?.content ?? "";
  const words = content.split(" ").length;
  return (<a href={props.hit.slug}>
    <div>
      <h3>{props?.hit?.frontmatter?.title ?? "no title"}</h3>
    </div>
    <p>{props?.hit?.frontmatter?.excerpt ?? ""}</p>
  </a>)
}

export default Hit;

검색 구성요소

이전 단계에서 구성한 InstantSearch 구성 요소 및 검색 클라이언트를 사용하고 인덱스 이름을 입력하고 AlgoliaSearchBox 구성 요소와 이전에 만든 빈 상태 동작이 변경된 사용자 지정Results 구성 요소를 사용합니다.

<InstantSearch indexName="simplelocalize-docs" searchClient={searchClient}>
    <SearchBox/>
    <Results/>
</InstantSearch>

필요 이상으로 복잡하게 만들고 싶지 않았습니다. 검색 버튼과 재설정 버튼을 숨기기 위해 스타일시트의 일부 CSS 속성을 덮어씁니다. 또한 SCSS@extend 속성을 사용하여 검색창에 부트스트랩 스타일을 추가했습니다. 간단하고 작업을 수행합니다.

.ais-SearchBox-input {
  @extend .form-control;
}

.ais-SearchBox-submit {
  display: none;
}

.ais-SearchBox-reset {
  display: none;
}

인덱싱할 마크다운 파일 가져오기

이제 인덱싱되고 검색 결과에 표시되어야 하는 모든 파일을 가져올 때입니다. CI/CD 서버에서 성공적으로 빌드할 때마다 실행할 새index-docs.js 파일을 만들었습니다. 모든 문서 페이지는 /docs/ 디렉토리에 있습니다. 그래서 Algolia 검색 색인을 채우기 위해 객체 배열로 변환하기 위한 스크립트를 작성해야 했습니다.

import {globby} from 'globby';
import fs from "fs";
import matter from "gray-matter";
import algoliasearch from 'algoliasearch';

const pages = await globby([
  'docs/',
]);

const objects = pages.map(page => {
  const fileContents = fs.readFileSync(page, 'utf8')
  const {data, content} = matter(fileContents)
  const path = page.replace('.md', '');
  let slug = path === 'docs/index' ? 'docs' : path;
  slug = "/" + slug + "/"
  return {
    slug,
    content,
    frontmatter: {
      ...data
    }
  }
})

//algolia update index code

/docs/ ,

가 있는 globby 디렉토리에서 모든 마크다운 파일을 가져옵니다.

fs ,

로 파일 내용 읽기

마크다운을 위해 gray-matter로 파일 구문 분석,

파일 경로를 사용되는 슬러그로 변환하는 몇 가지 마술을 수행합니다.

필자의 경우 슬러그는 파일 경로일 뿐이며 파일 경로는 /docs/{category}/{title}.md , 예: /docs/integrations/next-translate.md 이므로 슬러그는 다음과 같이 표시됩니다. /docs/integrations/next-translate/
결국 나는 다음과 같은 객체 배열을 얻습니다.

[
    {
      "slug": "/docs/integrations/next-translate/",
      "content": "My article content for indexing",
      "frontmatter": {
        "category": "Integrations",
        "date": "2022-01-20",
        "some-other-properties": "properties"
      }
    }
]

Algolia 지수 업데이트

Algolia는 정말 간단하고 사용하기 쉬운 JavaScript 클라이언트를 제공하므로 여기에 마법이 없습니다. 인덱스를 획득하고 이전 단계에서 생성한 개체를 저장합니다.

const client = algoliasearch(
  'APP_ID',
  'ADMIN_API_KEY'
);
const index = client.initIndex("simplelocalize-docs")
index.saveObjects(objects, {
  autoGenerateObjectIDIfNotExist: true
});

package.json에 인덱스 업데이트 포함

{
  "name": "simplelocalize-docs",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build && next export -o build/ && i18n:download && index:docs",
    "index:docs": "npx ts-node --skip-project index-docs.mjs",
    "i18n:upload": "simplelocalize upload",
    "i18n:download": "simplelocalize download"
  }
}

npm run index:docs 를 실행하여 스크립트를 수동으로 실행할 수 있습니다.



그게 다야? 그게 다야! SimpleLocalizedocumentation page에서 실행 중인 검색을 참조하십시오.