COM-140 search

.github/workflows/lint-test.yml

@@ -0,0 +1,25 @@
+name: Lint and test
+
+on:
+  push:
+    branches-ignore: [main]
+
+jobs:
+  setup:
+    name: Setup and install
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+      - name: Lint scripts
+        run: npm run lint
+      - name: Test application
+        run: npm run test run

README.md

@@ -34,3 +34,7 @@ If you would like to include additional standards, please refer to the [manual f
 
 - [Markdown metadata](./internal-docs/markdown-metadata.md)
 - [Markdown rules](./internal-docs/markdown-rules.md)
+
+### Seach
+
+- [Search overview](./internal-docs/search.md)

docusaurus.config.ts

@@ -96,6 +96,36 @@ const config: Config = {
       theme: prismThemes.github,
       darkTheme: prismThemes.dracula,
     },
+    algolia: {
+      // The application ID provided by Algolia
+      appId: 'NEXCQE76IQ',
+
+      // Public API key: it is safe to commit it
+      apiKey: '3ac1105b8b8b09af920cad8af52be9d0',
+
+      indexName: 'developers',
+
+      // Optional: see doc section below
+      contextualSearch: true,
+
+      // Optional: Specify domains where the navigation should occur through window.location instead on history.push. Useful when our Algolia config crawls multiple documentation sites and we want to navigate with window.location.href to them.
+      // externalUrlRegex: 'external\\.com|domain\\.com',
+
+      // Optional: Replace parts of the item URLs from Algolia. Useful when using the same search index for multiple deployments using a different baseUrl. You can use regexp or string in the `from` param. For example: localhost:3000 vs myCompany.com/docs
+      // replaceSearchResultPathname: {
+      //   from: '/docs/', // or as RegExp: /\/docs\//
+      //   to: '/',
+      // },
+
+      // Optional: Algolia search parameters
+      searchParameters: {},
+
+      // Optional: path for search page that enabled by default (`false` to disable it)
+      searchPagePath: 'search',
+
+      // Optional: whether the insights feature is enabled or not on Docsearch (`false` by default)
+      // insights: false,
+    },
   } satisfies Preset.ThemeConfig,
 };
 

eslint.config.mjs

@@ -18,6 +18,9 @@ export default tseslint.config(
         version: 'detect',
       },
     },
+    rules: {
+      'react/react-in-jsx-scope': 'off',
+    },
   },
   eslintPluginPrettierRecommended,
 );

internal-docs/search.md

@@ -0,0 +1,121 @@
+# Search
+
+This application uses Algolia for the search, as it is the [official Docusaurus search plugin](https://docusaurus.io/docs/search#using-algolia-docsearch) and provides a quick and easy search solution.
+
+## Config
+
+To implement this you need an Algolia Application. You can complete [this form](https://docsearch.algolia.com/apply/) and they will configure everything for you. Otherwise via the [Algolia dashboard](https://dashboard.algolia.com/), you need to create an Application.
+
+When creating an application manually, you need to link a `Crawler` to index the relevant content. Via the `Connectors` page you can link a `Crawler`. This comes with various config options, which can be seen when editing crawlers under the `Setup / Editor` page.
+
+The default Docusaurus v2 & v3 config should follow this template:
+
+```js
+new Crawler({
+  appId: 'YOUR_APP_ID',
+  apiKey: 'YOUR_API_KEY',
+  rateLimit: 8,
+  maxDepth: 10,
+  startUrls: ['https://YOUR_WEBSITE_URL/'],
+  sitemaps: ['https://YOUR_WEBSITE_URL/sitemap.xml'],
+  ignoreCanonicalTo: true,
+  discoveryPatterns: ['https://YOUR_WEBSITE_URL/**'],
+  actions: [
+    {
+      indexName: 'YOUR_INDEX_NAME',
+      pathsToMatch: ['https://YOUR_WEBSITE_URL/**'],
+      recordExtractor: ({ $, helpers }) => {
+        // priority order: deepest active sub list header -> navbar active item -> 'Documentation'
+        const lvl0 =
+          $(
+            '.menu__link.menu__link--sublist.menu__link--active, .navbar__item.navbar__link--active'
+          )
+            .last()
+            .text() || 'Documentation';
+
+        return helpers.docsearch({
+          recordProps: {
+            lvl0: {
+              selectors: '',
+              defaultValue: lvl0,
+            },
+            lvl1: ['header h1', 'article h1'],
+            lvl2: 'article h2',
+            lvl3: 'article h3',
+            lvl4: 'article h4',
+            lvl5: 'article h5, article td:first-child',
+            lvl6: 'article h6',
+            content: 'article p, article li, article td:last-child',
+          },
+          indexHeadings: true,
+          aggregateContent: true,
+          recordVersion: 'v3',
+        });
+      },
+    },
+  ],
+  initialIndexSettings: {
+    YOUR_INDEX_NAME: {
+      attributesForFaceting: [
+        'type',
+        'lang',
+        'language',
+        'version',
+        'docusaurus_tag',
+      ],
+      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',
+      separatorsToIndex: '_',
+    },
+  },
+});
+```
+
+A lot of these simpler options can also be configured through the `Setup / Configuration` page.
+
+**Note the return from `recordExtractor` in line 42 has been edited, changing `lvl1: ['header h1', 'article h1'],` to `lvl1: ['article h1'],` otherwise the indexer will also index the word `Developers` from the global header title.**