[Docs] DocSearch implementation

liyasthomas commented 1 year ago

I couldn't find a guide or example on how to implement DocSearch in Docus.

DocSearch was introduced in #22 but no documentation on how to implement the feature. I'd appreciate if anyone can share any resources that'll help users to integrate DocSearch.

engelnico commented 1 year ago

Docus automatically displays the search bar when you correctly add runtimeConfig for algolia/docsearch.

You can see it here: https://github.com/nuxt-themes/docus/blob/f56cd8d66441f7a60ad19a8644656c925f9f1747/app/integrations/docsearch.ts#L9

So you need to set the following in your nuxt.config.ts, such that hasDocSearch is true

export default defineNuxtConfig({
...
runtimeConfig: {
    public: {
      algolia: {
        applicationId: "",
        apiKey: "",
        langAttribute: "lang",
        docSearch: {
          indexName: "content-nuxtjs",
        },
      },
    },
  },
...
})

When you look at AppHeader.vue, you see that it then displays the Search bar https://github.com/nuxt-themes/docus/blob/f56cd8d66441f7a60ad19a8644656c925f9f1747/components/app/AppHeader.vue#L27

If you want to style the Searchbar component, just add a components/AppSearch.vue with the content from components/app/AppSearch.vue and adapt it to your needs.

It maybe possible that you have to manually install @docsearch/js.

Hope it helps for now, until it is added to the documentation.

liyasthomas commented 1 year ago

I was able to implement DocSearch by myself for Hoppscotch Documentation.

Prerequisite:

Install @docsearch/js as a dev dependency in your Docus project.

Step 1: Get DocSearch access.

Apply for DocSearch access → | Read Algolia DocSearch Documentation →

Once you get DocSearch access, you should now have an Algolia DocSearch app in your Algolia Dashboard. DocSearch comes with an active Algolia Crawler instance as well.

From the Algolia Crawler Dashboard > Editor, you can edit the Crawler configuration to fetch the markdown/html data from Docus deployment URL periodically.

Here's the Crawler configuration I used to fetch data from our Docus deployment URL

> **Warning** > If you're using this configuration, replace the URL `https://docs.hoppscotch.io` with your own Docus deployment URL. Replace `appId` and `apiKey` with your own keys. **Algolia Crawler Dashboard** > **Editor:** ```javascript new Crawler({ rateLimit: 8, maxDepth: 10, startUrls: ["https://docs.hoppscotch.io"], renderJavaScript: false, sitemaps: [], ignoreCanonicalTo: false, discoveryPatterns: ["https://docs.hoppscotch.io/**"], schedule: "at 15:52 on Monday", actions: [ { indexName: "hoppscotch", pathsToMatch: ["https://docs.hoppscotch.io/**"], recordExtractor: ({ helpers }) => { return helpers.docsearch({ recordProps: { lvl1: ["header h1", "article h1", "main h1", "h1", "head > title"], content: ["article p, article li", "main p, main li", "p, li"], lvl0: { selectors: "", defaultValue: "Documentation", }, lvl2: ["article h2", "main h2", "h2"], lvl3: ["article h3", "main h3", "h3"], lvl4: ["article h4", "main h4", "h4"], lvl5: ["article h5", "main h5", "h5"], lvl6: ["article h6", "main h6", "h6"], }, aggregateContent: true, recordVersion: "v3", }); }, }, ], initialIndexSettings: { hoppscotch: { attributesForFaceting: ["type", "lang"], attributesToRetrieve: [ "hierarchy", "content", "anchor", "url", "url_without_anchor", "type", ], attributesToHighlight: ["hierarchy", "content"], attributesToSnippet: ["content:10"], camelCaseAttributes: ["hierarchy", "content"], searchableAttributes: [ "unordered(hierarchy.lvl0)", "unordered(hierarchy.lvl1)", "unordered(hierarchy.lvl2)", "unordered(hierarchy.lvl3)", "unordered(hierarchy.lvl4)", "unordered(hierarchy.lvl5)", "unordered(hierarchy.lvl6)", "content", ], distinct: true, attributeForDistinct: "url", customRanking: [ "desc(weight.pageRank)", "desc(weight.level)", "asc(weight.position)", ], ranking: [ "words", "filters", "typo", "attribute", "proximity", "exact", "custom", ], highlightPreTag: '', highlightPostTag: "", minWordSizefor1Typo: 3, minWordSizefor2Typos: 7, allowTyposOnNumericTokens: false, minProximity: 1, ignorePlurals: true, advancedSyntax: true, attributeCriteriaComputedByMinProximity: true, removeWordsIfNoResults: "allOptional", }, }, appId: "xxxxxxxxxx", apiKey: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", }); ```

Once you get your Docus deployment indexed by Crawler, get your Algolia App's search API key, application ID, and Index name ready for step 2.

Note If your project got accepted to the DocSearch program, you should receive an email from Algolia Team with instructions to set up DocSearch. This email should contain your Algolia App's search API key, application ID, and Index name.

Step 2: Add environment variables in the `.env` file.

# Algolia API key and application ID
ALGOLIA_SEARCH_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
ALGOLIA_APPLICATION_ID="xxxxxxxxxx"
ALGOLIA_INDEX_NAME="xxxxxxx"

Step 3: Setup DocSearch environment variables in `nuxt.config.ts`.

export default defineNuxtConfig({
...
  runtimeConfig: {
    public: {
      algolia: {
        apiKey: process.env.ALGOLIA_SEARCH_API_KEY,
        applicationId: process.env.ALGOLIA_APPLICATION_ID,
        langAttribute: "lang",
        docSearch: {
          indexName: process.env.ALGOLIA_INDEX_NAME,
        },
      },
    },
  },
...
})

Restart your dev server to reflect the changes.

nuxt-themes / docus