8000 [Docs] DocSearch implementation · Issue #855 · nuxtlabs/docus · GitHub
[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content

[Docs] DocSearch implementation #855

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
liyasthomas opened this issue Mar 13, 2023 · 2 comments
Closed

[Docs] DocSearch implementation #855

liyasthomas opened this issue Mar 13, 2023 · 2 comments
Assignees
@bdrtsky
Labels
documentation Improvements or additions to documentation

Comments

@liyasthomas
Copy link

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.
@atinux atinux added the documentation Improvements or additions to documentation label Mar 13, 2023 — with Volta.net
@Tahul Tahul changed the title DocSearch implementation: Guide [Docs] DocSearch implementation May 17, 2023
@engelnico
Copy link

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
Copy link
Author
liyasthomas commented May 24, 2023 •
edited
Loading

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:

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: '<span class="algolia-docsearch-suggestion--highlight">',
      highlightPostTag: "</span>",
      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.

@bdrtsky bdrtsky self-assigned this Jun 19, 2023
@larbish larbish closed this as completed Jun 10, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@bdrtsky bdrtsky

Labels
documentation Improvements or additions to documentation
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
5 participants
@atinux @engelnico @larbish @liyasthomas @bdrtsky
0