Notebookshelf: Like mkdocs search, but across multiple sites

Notebook | bookshelf

Like mkdocs search, but across multiple sites.

Find multiple mkdocs sites, and want to search something, but don’t want to search them one by one? Notebookshelf is here to help you. It can index multiple mkdocs sites, and provide a unified search interface for you to search across all the indexed sites.

How to run (docker)

1. Clone the repository.

2. Configure which sites you want to index.

   [!NOTE]
   Each site should have a search_index.json file, which is generated by mkdocs with the search plugin.

   Usually if the site has a search box, it should have the search_index.json file by adding /search/search_index.json to the site URL. For example, if the site URL is https://example.com/docs/, then the search index file should be at https://example.com/docs/search/search_index.json.

   cp config.example.yml config.yml

   Then edit config.yml to add the paths to the search_index.json files of the sites you want to index.

3. Then you can run Notebookshelf with Docker:

docker compose build
docker compose up

4. Open http://localhost:8787 in your browser, and you will see the search interface.

Run locally without Docker

For frontend:

cd frontend
npm install
npm run dev # for development
npm run build && cp -r dist/* ../bookshelf/public/ # for production

For backend:

cp config.example.yml backend/config.yml
cd backend
npm install
npm run server

为什么想到做这个

阅读别人用Materials for MkDocs搭建的笔记，发现它的搜索功能只能搜索当前站点的内容（这很合理）；但是，我们有很多笔记站点，由不同人搭建。要是网站右上角那个搜索框能够跨站点搜索就好了。

mkdocs search

是基于lunr.js的，原理是把所有文档的内容都打包成一个json文件，前端搜索的时候直接在这个json文件上进行搜索。

这个文件位于<site_dir>/search/search_index.json，初步观察只要网站是用mkdocs搭建的，就会有这个搜索框，就可以找到这个文件。

{
    "config": {
        ...
    },
    "docs": [
        {
            "location": "...",
            "title": "...",
            "text": "..."
        },
        ...
    ]
}

首先是简短的config部分，随后就是docs，其中包含了所有文档的内容。每个文档包含location（URL），title和text（内容）。搜索的时候就是在这个text上进行搜索，找到匹配的文档，然后返回location和title。此外，目前看来他是根据小标题来分割的文档的，也就是说每个小标题下的内容会被当做一个独立的entry。