feat: support saving hash in filename instead of query

closes #171
easyops-cn · Jul 22, 2022 · 4930a88 · 4930a88
1 parent 6a9d0b7
commit 4930a88
Show file tree

Hide file tree

Showing 11 changed files with 67 additions and 23 deletions.
diff --git a/README.md b/README.md
@@ -76,7 +76,7 @@ module.exports = {
 | docsRouteBasePath                | string \| string[]                       | `"/docs"`    | Base route path(s) of docs. Slash at beginning is not required. Note: for [docs-only mode](https://docusaurus.io/docs/docs-introduction#docs-only-mode), this needs to be the same as `routeBasePath` in your `@docusaurus/preset-classic` config e.g., `"/"`. |
 | blogRouteBasePath                | string \| string[]                       | `"/blog"`    | Base route path(s) of blog. Slash at beginning is not required.                                                                                                                                                                                                |
 | language                         | string \| string[]                       | `"en"`       | All [lunr-languages](https://github.com/MihaiValentin/lunr-languages) supported languages, + `zh` 🔥.                                                                                                                                                          |
-| hashed                           | boolean                                  | `false`      | Whether to add a hashed query when fetching index (based on the content hash of all indexed `*.md` in `docsDir` and `blogDir` if applicable)                                                                                                                   |
+| hashed                           | boolean \| `"filename"` \| `"query"`     | `false`      | Whether to add a hashed query when fetching index (based on the content hash of all indexed `*.md` in `docsDir` and `blogDir` if applicable). Setting to `"filename"` will save hash in filename instead of query.                                             |
 | docsDir                          | string \| string[]                       | `"docs"`     | The dir(s) of docs to get the content hash, it's relative to the dir of your project.                                                                                                                                                                          |
 | blogDir                          | string \| string[]                       | `"blog"`     | Just like the `docsDir` but applied to blog.                                                                                                                                                                                                                   |
 | removeDefaultStopWordFilter      | boolean                                  | `false`      | Sometimes people (E.g., us) want to keep the English stop words as indexed, since they maybe are relevant in programming docs.                                                                                                                                 |

diff --git a/docusaurus-search-local/src/client/theme/SearchBar/fetchIndexes.ts b/docusaurus-search-local/src/client/theme/SearchBar/fetchIndexes.ts
@@ -4,7 +4,7 @@ import {
   SearchDocumentType,
   WrappedIndex,
 } from "../../../shared/interfaces";
-import { indexHash } from "../../utils/proxiedGenerated";
+import { searchIndexUrl } from "../../utils/proxiedGenerated";
 
 interface SerializedIndex {
   documents: SearchDocument[];
@@ -19,7 +19,7 @@ export async function fetchIndexes(baseUrl: string): Promise<{
 }> {
   if (process.env.NODE_ENV === "production") {
     const json = (await (
-      await fetch(`${baseUrl}search-index.json?_=${indexHash}`)
+      await fetch(`${baseUrl}${searchIndexUrl}`)
     ).json()) as SerializedIndex[];
 
     const wrappedIndexes: WrappedIndex[] = json.map(

diff --git a/docusaurus-search-local/src/client/utils/__mocks__/proxiedGenerated.ts b/docusaurus-search-local/src/client/utils/__mocks__/proxiedGenerated.ts
@@ -1,7 +1,7 @@
 export let language = ["en", "zh"];
 export let removeDefaultStopWordFilter = false;
 export let removeDefaultStemmer = false;
-export const indexHash = "abc";
+export const searchIndexUrl = "search-index.json?_=abc";
 export const searchResultLimits = 8;
 export const searchResultContextMaxLength = 50;
 export const explicitSearchResultPath = false;

diff --git a/docusaurus-search-local/src/declarations.ts b/docusaurus-search-local/src/declarations.ts
@@ -11,7 +11,7 @@ declare module "*/generated.js" {
     mark: (terms: string[], options?: Record<string, unknown>) => void;
     unmark: () => void;
   }
-  export const indexHash: string | undefined;
+  export const searchIndexUrl: string;
   export const searchResultLimits: number;
   export const searchResultContextMaxLength: number;
   export const explicitSearchResultPath: boolean;

diff --git a/docusaurus-search-local/src/server/index.ts b/docusaurus-search-local/src/server/index.ts
@@ -17,7 +17,7 @@ export default function DocusaurusSearchLocalPlugin(
 
   const dir = path.join(context.generatedFilesDir, PLUGIN_NAME, "default");
   fs.ensureDirSync(dir);
-  generate(config, dir);
+  const searchIndexFilename = generate(config, dir);
 
   const themePath = path.resolve(__dirname, "../../client/client/theme");
   const pagePath = path.join(themePath, "SearchPage/index.js");
@@ -29,7 +29,7 @@ export default function DocusaurusSearchLocalPlugin(
       return themePath;
     },
 
-    postBuild: postBuildFactory(config),
+    postBuild: postBuildFactory(config, searchIndexFilename),
 
     getPathsToWatch() {
       return [pagePath];

diff --git a/docusaurus-search-local/src/server/utils/generate.spec.ts b/docusaurus-search-local/src/server/utils/generate.spec.ts
@@ -23,7 +23,7 @@ describe("generate", () => {
         "export const removeDefaultStopWordFilter = false;",
         "export const removeDefaultStemmer = false;",
         "export const Mark = null;",
-        'export const indexHash = "abc";',
+        'export const searchIndexUrl = "search-index.json?_=abc";',
         "export const searchResultLimits = 8;",
         "export const searchResultContextMaxLength = 50;",
         "export const explicitSearchResultPath = false;",
@@ -44,7 +44,7 @@ describe("generate", () => {
         "export const removeDefaultStopWordFilter = false;",
         "export const removeDefaultStemmer = false;",
         "export const Mark = null;",
-        'export const indexHash = "abc";',
+        'export const searchIndexUrl = "search-index.json?_=abc";',
         "export const searchResultLimits = 8;",
         "export const searchResultContextMaxLength = 50;",
         "export const explicitSearchResultPath = false;",
@@ -67,7 +67,7 @@ describe("generate", () => {
         "export const removeDefaultStopWordFilter = false;",
         "export const removeDefaultStemmer = false;",
         "export const Mark = null;",
-        'export const indexHash = "abc";',
+        'export const searchIndexUrl = "search-index.json?_=abc";',
         "export const searchResultLimits = 8;",
         "export const searchResultContextMaxLength = 50;",
         "export const explicitSearchResultPath = false;",
@@ -93,7 +93,7 @@ describe("generate", () => {
         "export const removeDefaultStopWordFilter = false;",
         "export const removeDefaultStemmer = false;",
         "export const Mark = null;",
-        'export const indexHash = "abc";',
+        'export const searchIndexUrl = "search-index.json?_=abc";',
         "export const searchResultLimits = 8;",
         "export const searchResultContextMaxLength = 50;",
         "export const explicitSearchResultPath = false;",
@@ -117,7 +117,7 @@ describe("generate", () => {
         "export const removeDefaultStopWordFilter = false;",
         "export const removeDefaultStemmer = false;",
         "export const Mark = null;",
-        'export const indexHash = "abc";',
+        'export const searchIndexUrl = "search-index.json?_=abc";',
         "export const searchResultLimits = 8;",
         "export const searchResultContextMaxLength = 50;",
         "export const explicitSearchResultPath = false;",
@@ -144,7 +144,7 @@ describe("generate", () => {
         "export const removeDefaultStopWordFilter = false;",
         "export const removeDefaultStemmer = false;",
         "export const Mark = null;",
-        'export const indexHash = "abc";',
+        'export const searchIndexUrl = "search-index.json?_=abc";',
         "export const searchResultLimits = 8;",
         "export const searchResultContextMaxLength = 50;",
         "export const explicitSearchResultPath = false;",
@@ -215,7 +215,7 @@ describe("generate", () => {
     );
   });
 
-  test("searchBarShortcut", () => {
+  test("searchBarShortcutHint", () => {
     generate(
       {
         language: ["en"],
@@ -232,7 +232,8 @@ describe("generate", () => {
       expect.stringContaining("export const searchBarShortcutHint = false")
     );
   });
-  test("searchBarShortcut", () => {
+
+  test("docsPluginIdForPreferredVersion", () => {
     generate(
       {
         language: ["en"],
@@ -251,4 +252,24 @@ describe("generate", () => {
       )
     );
   });
+
+  test("hashed with filename", () => {
+    generate(
+      {
+        language: ["en"],
+        removeDefaultStopWordFilter: false,
+        searchResultLimits: 8,
+        searchResultContextMaxLength: 50,
+        hashed: "filename",
+      } as ProcessedPluginOptions,
+      "/tmp"
+    );
+
+    expect(mockWriteFileSync).toBeCalledWith(
+      "/tmp/generated.js",
+      expect.stringContaining(
+        'export const searchIndexUrl = "search-index-abc.json"'
+      )
+    );
+  });
 });
diff --git a/docusaurus-search-local/src/server/utils/generate.ts b/docusaurus-search-local/src/server/utils/generate.ts
@@ -3,7 +3,7 @@ import path from "path";
 import { ProcessedPluginOptions } from "../../shared/interfaces";
 import { getIndexHash } from "./getIndexHash";
 
-export function generate(config: ProcessedPluginOptions, dir: string): void {
+export function generate(config: ProcessedPluginOptions, dir: string): string {
   const {
     language,
     removeDefaultStopWordFilter,
@@ -75,7 +75,21 @@ export function generate(config: ProcessedPluginOptions, dir: string): void {
   } else {
     contents.push("export const Mark = null;");
   }
-  contents.push(`export const indexHash = ${JSON.stringify(indexHash)};`);
+
+  let searchIndexFilename = "search-index.json";
+  let searchIndexQuery = "";
+
+  if (indexHash) {
+    if (config.hashed === "filename") {
+      searchIndexFilename = `search-index-${indexHash}.json`;
+    } else {
+      searchIndexQuery = `?_=${indexHash}`;
+    }
+  }
+  const searchIndexUrl = searchIndexFilename + searchIndexQuery;
+  contents.push(
+    `export const searchIndexUrl = ${JSON.stringify(searchIndexUrl)};`
+  );
   contents.push(
     `export const searchResultLimits = ${JSON.stringify(searchResultLimits)};`,
     `export const searchResultContextMaxLength = ${JSON.stringify(
@@ -104,4 +118,6 @@ export function generate(config: ProcessedPluginOptions, dir: string): void {
   );
 
   fs.writeFileSync(path.join(dir, "generated.js"), contents.join("\n"));
+
+  return searchIndexFilename;
 }
diff --git a/docusaurus-search-local/src/server/utils/postBuildFactory.ts b/docusaurus-search-local/src/server/utils/postBuildFactory.ts
@@ -9,7 +9,10 @@ import { scanDocuments } from "./scanDocuments";
 
 const writeFileAsync = util.promisify(fs.writeFile);
 
-export function postBuildFactory(config: ProcessedPluginOptions) {
+export function postBuildFactory(
+  config: ProcessedPluginOptions,
+  searchIndexFilename: string
+) {
   return async function postBuild(buildData: PostBuildData): Promise<void> {
     debugInfo("gathering documents");
 
@@ -28,7 +31,7 @@ export function postBuildFactory(config: ProcessedPluginOptions) {
       debugInfo("writing index to disk");
 
       await writeFileAsync(
-        path.join(versionData.outDir, "search-index.json"),
+        path.join(versionData.outDir, searchIndexFilename),
         JSON.stringify(searchIndex),
         { encoding: "utf8" }
       );

diff --git a/docusaurus-search-local/src/server/utils/validateOptions.spec.ts b/docusaurus-search-local/src/server/utils/validateOptions.spec.ts
@@ -152,13 +152,14 @@ describe("validateOptions", () => {
         docsRouteBasePath: "/dev/docs",
         blogRouteBasePath: "/dev/blog",
         searchBarShortcutHint: false,
+        hashed: true,
       },
       {
         blogRouteBasePath: "/dev/blog",
         blogDir: ["blog"],
         docsRouteBasePath: "/dev/docs",
         docsDir: ["docs"],
-        hashed: false,
+        hashed: true,
         indexBlog: true,
         indexDocs: true,
         indexPages: false,
@@ -179,13 +180,14 @@ describe("validateOptions", () => {
         docsRouteBasePath: ["/dev/docs"],
         blogRouteBasePath: ["/dev/blog"],
         docsPluginIdForPreferredVersion: "product",
+        hashed: "filename",
       },
       {
         blogRouteBasePath: ["/dev/blog"],
         blogDir: ["blog"],
         docsRouteBasePath: ["/dev/docs"],
         docsDir: ["docs"],
-        hashed: false,
+        hashed: "filename",
         indexBlog: true,
         indexDocs: true,
         indexPages: false,

diff --git a/docusaurus-search-local/src/server/utils/validateOptions.ts b/docusaurus-search-local/src/server/utils/validateOptions.ts
@@ -11,6 +11,8 @@ const isStringOrArrayOfStrings = Joi.alternatives().try(
   Joi.array().items(Joi.string())
 );
 
+const isBooleanOrString = Joi.alternatives().try(Joi.boolean(), Joi.string());
+
 const isArrayOfStringsOrRegExpsOrStringOrRegExp = Joi.alternatives().try(
   Joi.array().items(Joi.alternatives().try(Joi.string(), Joi.object().regex())),
   Joi.string(),
@@ -24,7 +26,7 @@ const schema = Joi.object<PluginOptions>({
   docsRouteBasePath: isStringOrArrayOfStrings.default(["docs"]),
   blogRouteBasePath: isStringOrArrayOfStrings.default(["blog"]),
   language: isStringOrArrayOfStrings.default(["en"]),
-  hashed: Joi.boolean().default(false),
+  hashed: isBooleanOrString.default(false),
   docsDir: isStringOrArrayOfStrings.default(["docs"]),
   blogDir: isStringOrArrayOfStrings.default(["blog"]),
   removeDefaultStopWordFilter: Joi.boolean().default(false),

diff --git a/docusaurus-search-local/src/shared/interfaces.ts b/docusaurus-search-local/src/shared/interfaces.ts
@@ -138,7 +138,7 @@ export interface PluginOptions {
   docsRouteBasePath?: string | string[];
   blogRouteBasePath?: string | string[];
   language?: string | string[];
-  hashed?: boolean;
+  hashed?: boolean | "query" | "filename";
   docsDir?: string | string[];
   blogDir?: string | string[];
   docsPluginIdForPreferredVersion?: string;