UI: Improve navigation system of in-game documentation viewer (#2499)

* UI: Improve navigation system of in-game documentation viewer

* Update based on feedback

* Update based on feedback

src/ui/React/Documentation.tsx

@@ -1,5 +1,5 @@
 import React, { useContext, useState } from "react";
-import { type FilePath, asFilePath } from "../../Paths/FilePath";
+import { type FilePath, asFilePath, resolveFilePath } from "../../Paths/FilePath";
 import { CONSTANTS } from "../../Constants";
 import { resolvePage } from "../../Documentation/root";
 
@@ -21,7 +21,7 @@ interface History {
   home(): void;
 }
 
-const defaultPage = asFilePath("index.md");
+export const defaultPage = asFilePath("index.md");
 export const defaultNsApiPage = asFilePath("nsDoc/bitburner.ns.md");
 /**
  * If we move or rename "bitburner.ns.md", we must update this constant, "defaultNsApiPage", "openDocExternally", and
@@ -31,6 +31,8 @@ export const externalUrlOfNsApiPage =
   "https://github.com/bitburner-official/bitburner-src/blob/stable/markdown/bitburner.ns.md";
 export const prefixOfHttpUrlOfNsDocs = "https://github.com/bitburner-official/bitburner-src/blob/stable/markdown/";
 
+const prefixOfRelativeUrlOfNSDoc = "../../../../markdown/bitburner.";
+
 const HistoryContext = React.createContext<History>({
   page: defaultPage,
   pages: [],
@@ -92,7 +94,7 @@ export const HistoryProvider = (props: React.PropsWithChildren<object>): React.R
   return <Provider value={history}>{props.children}</Provider>;
 };
 
-export function openDocExternally(path: string) {
+export function openDocExternally(path: string): void {
   const ver = CONSTANTS.isDevBranch ? "dev" : "stable";
   let url;
   if (path.startsWith("http://") || path.startsWith("https://")) {
@@ -111,3 +113,55 @@ export function openDocExternally(path: string) {
   }
   window.open(url, "_newtab");
 }
+
+/**
+ * Href can be:
+ * - Relative URL from non-NS docs pointing to markdown folder: Open "../../../../markdown/bitburner.ns.md" from "index.md"
+ * - Relative URL from NS docs to other NS docs (e.g., click the links in NS docs viewer): Open "./bitburner.ns.cloud.md" from "nsDoc/bitburner.ns.md"
+ * - Internal NS docs (e.g., choose a dropdown option in DocumentationAutocomplete): nsDoc/bitburner.ns.md
+ * - Internal non-NS docs: help/getting_started.md
+ * - HTTP URL:
+ *   - Point to NS docs. Some non-NS docs pages include links to NS docs. For example: basic/scripts.md has a
+ * link to https://github.com/bitburner-official/bitburner-src/blob/stable/markdown/bitburner.ns.flags.md. In
+ * these cases, the link always points to a file at https://github.com/bitburner-official/bitburner-src/blob/stable/markdown/
+ *   - Point to other places.
+ */
+export function convertNavigatorHref(
+  href: string,
+  currentPage: FilePath,
+): { path: FilePath | null; forceOpenExternally: false } | { path: string; forceOpenExternally: true } {
+  let path;
+  if (href.includes(prefixOfRelativeUrlOfNSDoc)) {
+    // Relative URL from non-NS docs pointing to markdown folder
+    path = asFilePath(
+      // Convert "../../../../markdown/bitburner.foo.md" and "deeper" URLs (i.e., having more "../") to "nsDoc/bitburner.foo.md"
+      href.replace(
+        href.substring(0, href.indexOf(prefixOfRelativeUrlOfNSDoc) + prefixOfRelativeUrlOfNSDoc.length),
+        "nsDoc/bitburner.",
+      ),
+    );
+  } else if (/^\.\/bitburner\.[^/]*\.md$/.test(href)) {
+    // Relative URL from NS docs to other NS docs. The URL is always ./bitburner.foo.md
+    // - Start with "./bitburner."
+    // - End with ".md"
+    // - Never have "/" between "./bitburner." and ".md"
+    path = resolveFilePath(href, defaultNsApiPage);
+  } else if (href.startsWith("nsDoc/")) {
+    // Internal NS docs
+    path = asFilePath(href);
+  } else if (href.startsWith("https://") || href.startsWith("http://")) {
+    // TODO: Remove this case after converting all these links to relative links.
+    // HTTP URL pointing to NS docs.
+    // Convert https://github.com/bitburner-official/bitburner-src/blob/stable/markdown/bitburner.foo.md to nsDoc/bitburner.foo.md
+    if (href.startsWith(prefixOfHttpUrlOfNsDocs)) {
+      path = asFilePath(`nsDoc/${href.replace(prefixOfHttpUrlOfNsDocs, "")}`);
+    } else {
+      // HTTP URL pointing to other places.
+      return { path: href, forceOpenExternally: true };
+    }
+  } else {
+    // Internal non-NS docs
+    path = resolveFilePath("./" + href, currentPage);
+  }
+  return { path, forceOpenExternally: false };
+}