Docs as code - (3) Docusaurus 페이지에 대해 Typesense scraper로 검색 인덱스가 잘 생성되지 않는 문제 해결

Docs as code - (2) Docusaurus v3의 On-premise 검색 엔진으로 Typesense 사용 하기

Docs as code - (2) Docusaurus v3의 On-premise 검색 엔진으로 Typesense 사용 하기

기존 포스트를 통해 Typesense를 사용하여 검색 인덱스를 생성 했었는데, 일부 문제가 있어서 해결하려고 합니다.

Scraper를 통해서 index를 생성했는데 원하는 페이지들이 검색이 안되는 문제가 있었습니다.

필요한 내용에 대한 검색이 잘 안되었습니다.

이를 해결하는 방법을 찾고 정리하고 있습니다.

 

근본 원인 : 검색 Index가 충분히 생성되지 않는 문제

1. 위의 top menu에서 다른 menu의 내용이 검색이 안되는 문제

저의 예시에서 User Guide를 누르면 Packer QEMU Template이라는 문서가 있는데 packer를 통해서 검색하면 아무것도 뜨지 않는 문제가 있었습니다.

아무래도 docusaurus.json 파일을 추가 해야 검색이 될것 같다는 생각이 들었습니다.

기존 docusaurus.json

{
  "index_name": "mycollection",
  "start_urls": [
    "http://host.docker.internal"
  ],
  "js_wait": 2,
  "js_render": true,
  "sitemap_alternate_links": true,
  "selectors": {
    "default": {
      "lvl0": "h1",
      "lvl1": "h2",
      "lvl2": "h3",
      "lvl3": "h4",
      "lvl4": "h5",
      "text": "p, .theme-default-content ul li, .theme-default-content table tbody tr"
    }
  },
  "strip_chars": " .,;:#",
  "custom_settings": {
    "separatorsToIndex": "_",
    "attributesForFaceting": [
      "language",
      "version",
      "type",
      "docusaurus_tag"
    ],
    "attributesToRetrieve": [
      "hierarchy",
      "content",
      "anchor",
      "url",
      "url_without_anchor",
      "type"
    ]
  }
}

start url이 ADR & architecture Design 메뉴에서 시작해서 그런가 싶어서 몇개를 더 추가해보려고 합니다.

또한, 이 파일에서 여기서 몇 가지 부족한 점이 있어서 검색이 안되는것이라 생각해서 이를 강화하여 테스트를 해보았습니다.

 

아래와 같이 4개의 메뉴의 시작 url을 추가했습니다.

그리고 Sitemap도 추가했습니다.

변경된 docusaurus.json

{
  "index_name": "mycollection",
  "start_urls": [
    "http://host.docker.internal/docusaurus-template/adr-architecture/intro",
    "http://host.docker.internal/docusaurus-template/userguide/packer-qemu-template",
    "http://host.docker.internal/docusaurus-template/srs/portfolio-assist",
    "http://host.docker.internal/docusaurus-template/api/sample-api"
  ],
  "sitemap_urls": [
    "http://host.docker.internal/docusaurus-template/sitemap.xml"
  ],
  "js_wait": 2,
  "js_render": true,
  "sitemap_alternate_links": true,
  "selectors": {
    "lvl0": {
      "selector": "(//ul[contains(@class,'menu__list')]//a[contains(@class, 'menu__link menu__link--sublist menu__link--active')]/text() | //nav[contains(@class, 'navbar')]//a[contains(@class, 'navbar__link--active')]/text())[last()]",
      "type": "xpath",
      "global": true,
      "default_value": "Documentation"
    },
    "lvl1": "header h1",
    "lvl2": "article h2",
    "lvl3": "article h3",
    "lvl4": "article h4",
    "lvl5": "article h5, article td:first-child",
    "lvl6": "article h6",
    "text": "article p, article li, article td:last-child"
  },
  "strip_chars": " .,;:#",
  "custom_settings": {
    "separatorsToIndex": "_",
    "attributesForFaceting": [
      "language",
      "version",
      "type",
      "docusaurus_tag"
    ],
    "attributesToRetrieve": [
      "hierarchy",
      "content",
      "anchor",
      "url",
      "url_without_anchor",
      "type"
    ]
  }
}

그 이후에 typesense-scraper를 실행했더니 확실히 nbHits 숫자가 아래와 같이 늘어남을 확인할 수 있었습니다.

기존의 Nb Hits:19

변경된 json으로 했을때 Nb hits: 103

검색 결과 또한 Packer 내용을 검색할 수 있었습니다

Packer가 검색되는 모습

 

2. 사이드바에서 폴더 내부에 있는 파일에 대한 검색이 안되는 문제

여기의 예시에서 tutorial-basics 밑에 Congratulations! 문서를 찾지 못하는 문제가 있었습니다.

아무래도 설정을 추가해야할 것 같다는 생각이 들었습니다.

 

그래서 이게 가능한지 아닌지를 보기 위해서 기존 Docusaurus 사이트의 algoria도 category 하위의 문서를 검색할 수 있는지 확인해봤습니다.

Category 밑의 문서도 검색이 되는것을 확인했습니다.

심지어는 Category/Category/Doc 구조도 검색이 됩니다.

이를 가능하게 하는 Config 설정을 확인해야 할 것 같습니다.

 

우선은 아래와 같이 단순히 start urls를 추가 해 봤습니다.

{
  "index_name": "mycollection",
  "start_urls": [
    "http://host.docker.internal/docusaurus-template/adr-architecture/intro",
    "http://host.docker.internal/docusaurus-template/userguide/packer-qemu-template",
    "http://host.docker.internal/docusaurus-template/srs/portfolio-assist",
    "http://host.docker.internal/docusaurus-template/api/sample-api",
    "http://host.docker.internal/docusaurus-template/adr-architecture/tutorial-basics"
  ],

start_urls의 마지막에 tutorial-basics category를 추가하니까 nbHits가 추가되어서 검색이 가능했습니다.

검색도 가능합니다.

다만, 이런방식으로 해결 하는 경우에는 너무 많은 url을 추가해야해서 좋은 방법은 아닐거라고 생각이 들었습니다.

 

Sitemap.xml을 잘 읽으면 start urls를 사용할 필요 없이 잘 될것 같은데 현재 설정으로는 그런 상황은 또 아닌것 같습니다.

 

그래서 좀 찾아보다가 

CoCalc -- typesense-scrape-config.json

CoCalc -- typesense-scrape-config.json

https://docs.nocodb.com/

Welcome | NocoDB

이 사이트의 예시 config를 봤는데 start url이 정말 배포된 첫 주소를 의미하는것 같고 sitemap만 잘 지정해 주면 categories에 대해서도 검색이 잘 되는것 같아서 저도 start urls를 배포 기본 주소로만 설정해봤습니다.

저의 경우에 제 기본 배포주소는 

http://host.docker.internal/docusaurus-template 입니다.

처음에는 해당 주소를 http://host.docker.internal/docusaurus-template/adr-architecture/intro 로 redirection 해두었기에 start url도 http://host.docker.internal/docusaurus-template/adr-architecture/intro 여기 주소로 했었는데 혹시 이것이 잘못되었나 싶어 시도를 해봤습니다.

{
  "index_name": "mycollection",
  "start_urls": [
    "http://host.docker.internal/docusaurus-template"
  ],
  "sitemap_urls": [
    "http://host.docker.internal/docusaurus-template/sitemap.xml"
  ],
  "js_wait": 2,
  "js_render": true,
  "sitemap_alternate_links": true,
  "selectors": {
    "lvl0": {
      "selector":"(//ul[contains(@class,'menu__list')]//a[contains(@class, 'menu__link menu__link--sublist menu__link--active')]/text() | //nav[contains(@class, 'navbar')]//a[contains(@class, 'navbar__link--active')]/text())[last()]",
      "type": "xpath",
      "global": true,
      "default_value": "Documentation"
    },
    "lvl1": "article h1, header h1",
    "lvl2": "article h2",
    "lvl3": "article h3",
    "lvl4": "article h4",
    "lvl5": "article h5, article td:first-child",
    "lvl6": "article h6",
    "text": "article p, article li, article td:last-child"
  },
  "strip_chars": " .,;:#",
  "custom_settings": {
    "separatorsToIndex": "_",
    "attributesForFaceting": [
      "language",
      "version",
      "type",
      "docusaurus_tag"
    ],
    "attributesToRetrieve": [
      "hierarchy",
      "content",
      "anchor",
      "url",
      "url_without_anchor",
      "type"
    ]
  }
}

그래서 위와 같은 설정으로 했더니 NbHits가 많이 뜨는것을 볼 수있었습니다!!!

무려 NbHits가 370!

 

Nested Categories에 대해 검색 결과도 잘 보이는 모습을 확인할 수 있었습니다.

tutorial-basics/adr-architecture/new-file/Congratulations 파일이 잘 검색되는 모습

또 하나 문제가 있다면 API에 대한 문서는 검색이 안된다는것인데 crawling rule에서 정하는 포맷과 일치하지 않아서 생기는 문제인것으로 생각되어 이를 추가로 확인 해 볼 예정입니다.

 

3. API documentation 에 대한 인덱스 생성이 안됨

모든 API Documentation이 index가 생성되지 않는건 아니였습니다.

일부 안되는 경우는 crawling 시에 에러를 발생시키는 문제가 있습니다.

이상해서 조금 더 살펴보니 js_wait이 2초라서 충분하지 않았던 문제가 있었던것 같습니다.

그래서 js_wait 값을 4초로 늘려줬더니 에러가 났던 crawling에서 성공하였습니다.

{
  "index_name": "mycollection",
  "start_urls": [
    "http://host.docker.internal/docusaurus-template"
  ],
  "sitemap_urls": [
    "http://host.docker.internal/docusaurus-template/sitemap.xml"
  ],
  "js_wait": 4,
  "js_render": true,
  "sitemap_alternate_links": true,
  "selectors": {
    "lvl0": {
      "selector":"(//ul[contains(@class,'menu__list')]//a[contains(@class, 'menu__link menu__link--sublist menu__link--active')]/text() | //nav[contains(@class, 'navbar')]//a[contains(@class, 'navbar__link--active')]/text())[last()]",
      "type": "xpath",
      "global": true,
      "default_value": "Documentation"
    },
    "lvl1": "article h1, header h1",
    "lvl2": "article h2",
    "lvl3": "article h3",
    "lvl4": "article h4",
    "lvl5": "article h5, article td:first-child",
    "lvl6": "article h6",
    "text": "article p, article li, article td:last-child"
  },
  "strip_chars": " .,;:#",
  "custom_settings": {
    "separatorsToIndex": "_",
    "attributesForFaceting": [
      "language",
      "version",
      "type",
      "docusaurus_tag"
    ],
    "attributesToRetrieve": [
      "hierarchy",
      "content",
      "anchor",
      "url",
      "url_without_anchor",
      "type"
    ]
  }
}

이를 통해서 NbHits를 525까지 최대로 늘렸습니다!

또한 검색도 잘 되는 모습을 볼 수 있습니다.

API 검색도 잘 되는 모습

 

4. 버전별 URL index 검색 지원

버전 별 링크를 추가하기 위해서 아래 링크를 활용해야 할 것 같습니다.

Config Files | DocSearch by Algolia

Config Files | DocSearch by Algolia

Allow passing custom collection options · Issue #33 · typesense/typesense-docsearch-scraper

Allow passing custom collection options · Issue #33 · typesense/typesense-docsearch-scraper

 

(추가) 위의 링크들을 활용하지 않고 일단 version을 위한 document와 파일들만 추가한  index를 생성해봤습니다.

sitemap을 알아서 잘 읽고 version을 잘 추가하는것 같고 검색도 잘 되는것같습니다.

1.10 version에 대해서 검색 index를 잘 생성한모습

그리고 typesense에서도 버전별로 검색을 지원하고있어서 편하게 검색이 가능한 모습을 볼 수 있었습니다.

 

아래 예시에서는 1.10 버전에서는 Next 버전에 있는 일부 문서들을 제외하였고 

제외된 문서들이 1.10 버전의 typesense 검색에서는 정상적으로 검색 되지 않는 모습을 볼 수 있었습니다.

버전별 검색을 지원함 : 1.10 버전에 대한 검색 지원

버전별 검색을 지원함 : Next 버전의 검색 결과와 다르게 잘 나오는 모습