Allow submodule version aliases for import paths

Closes #195

Add a `remark` plugin that lets a docs author include an `import`
statement that points to a directory in the current version submodule of
the docs site. This makes it possible to import the path of a static
asset or, with the `!!raw-loader!` directive, the full content, using an
`import` statement, without having to know which versioned submodule an
asset is in at a given time.

To use this, add the string `@version` to the start of an import path,
e.g.,:

```jsx
import PNGPath from '@version/docs/img/myimg.png'
```

In a `gravitational/teleport` clone at the current default version of
the docs site, the new plugin would add the following:

```jsx
import PNGPath from '@site/content/17.x/docs/img/myimg.png'
```

Note that we currently use a workaround in which we place some static
assets in the `/static` directory, which exists outside the submodule
directory tree. This is approach is cumbersome since it requires a
change to `docs-website` for every asset we want to include using an
`import` statement.

The `@site` alias is a Docusaurus feature that the docs engine replaces
with the root path of the Docusaurus project. The plugin fills in the
path of the current `gravitational/teleport` submodule.

To import the content of a text asset, rather than the file path, you
would use the `!!raw-loader` syntax as you would for any Docusaurus
asset:

```jsx
import PNGPath from '!!raw-loader!@version/docs/img/myimg.png'
```

Author: ptgott

docusaurus.config.ts

@@ -12,6 +12,7 @@ import {
 import remarkUpdateAssetPaths from "./server/remark-update-asset-paths";
 import remarkIncludes from "./server/remark-includes";
 import remarkVariables from "./server/remark-variables";
+import remarkVersionAlias from "./server/remark-version-alias";
 import remarkCodeSnippet from "./server/remark-code-snippet";
 import { fetchVideoMeta } from "./server/youtube-meta";
 import { getRedirects } from "./server/redirects";
@@ -214,6 +215,7 @@ const config: Config = {
         versions: getDocusaurusConfigVersionOptions(),
         // Our custom plugins need to be before default plugins
         beforeDefaultRemarkPlugins: [
+          [remarkVersionAlias, latestVersion],
           [
             remarkIncludes,
             {

package.json

@@ -56,16 +56,19 @@
     "@docusaurus/tsconfig": "^3.7.0",
     "@inkeep/cxkit-react": "^0.5.71",
     "@mdx-js/react": "^3.0.0",
+    "@types/estree": "^1.0.7",
     "classnames": "^2.3.1",
     "clsx": "^2.1.1",
     "date-fns": "^4.1.0",
     "dotenv": "^16.5.0",
     "highlightjs-terraform": "https://github.com/highlightjs/highlightjs-terraform#eb1b9661e143a43dff6b58b391128ce5cdad31d4",
     "lowlight": "^3.1.0",
     "mdast-util-from-markdown": "^2.0.1",
+    "mdast-util-mdxjs-esm": "^2.0.1",
     "nanoid": "^5.1.0",
     "postcss-preset-env": "^10.1.6",
     "prism-react-renderer": "^2.3.0",
+    "raw-loader": "^4.0.2",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "react-loadable": "^5.5.0",
@@ -139,4 +142,4 @@
   "engines": {
     "node": ">=18.0"
   }
-}
+}

server/remark-version-alias.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, test } from "@jest/globals";
+import { VFile, VFileOptions } from "vfile";
+import { remark } from "remark";
+import mdx from "remark-mdx";
+import remarkVersionAlias from "./remark-version-alias";
+import remarkFrontmatter from "remark-frontmatter";
+
+const transformer = (vfileOptions: VFileOptions) => {
+  const file: VFile = new VFile(vfileOptions);
+
+  return remark()
+    .use(mdx as any)
+    .use(remarkFrontmatter) // Test cases use frontmatter
+    .use(remarkVersionAlias as any, "15.x")
+    .processSync(file as any);
+};
+
+describe("server/remark-version-alias", () => {
+  interface testCase {
+    description: string;
+    input: string;
+    expected: string;
+    path: string;
+  }
+
+  const testCases: Array<testCase> = [
+    {
+      description: "import statement in latest-version docs path",
+      input: `---
+title: My page
+description: My page
+---
+
+import CodeExample from "@version/examples/access-plugin-minimal/config.go"
+
+This is a paragraph.`,
+      expected: `---
+title: My page
+description: My page
+---
+
+import CodeExample from '@site/content/15.x/examples/access-plugin-minimal/config.go'
+
+This is a paragraph.
+`,
+      path: "docs/mypage.mdx",
+    },
+    {
+      description: "import statement in non-latest docs path",
+      input: `---
+title: My page
+description: My page
+---
+
+import CodeExample from "@version/examples/access-plugin-minimal/config.go"
+
+This is a paragraph.`,
+      expected: `---
+title: My page
+description: My page
+---
+
+import CodeExample from '@site/content/16.x/examples/access-plugin-minimal/config.go'
+
+This is a paragraph.
+`,
+      path: "versioned_docs/version-16.x/mypage.mdx",
+    },
+{
+      description: "raw loader",
+      input: `---
+title: My page
+description: My page
+---
+
+import CodeExample from "!!raw-loader!@version/examples/access-plugin-minimal/config.go"
+
+This is a paragraph.`,
+      expected: `---
+title: My page
+description: My page
+---
+
+import CodeExample from '!!raw-loader!@site/content/16.x/examples/access-plugin-minimal/config.go'
+
+This is a paragraph.
+`,
+      path: "versioned_docs/version-16.x/mypage.mdx",
+    },
+  ];
+
+  test.each(testCases)("$description", (tc) => {
+    const result = transformer({
+      value: tc.input,
+      path: tc.path,
+    }).toString();
+
+    expect(result).toEqual(tc.expected);
+  });
+});

server/remark-version-alias.ts

@@ -0,0 +1,55 @@
+import type { ImportDeclaration } from "estree";
+import type { MdxjsEsm } from "mdast-util-mdxjs-esm";
+import type { Root, Paragraph, Literal } from "mdast";
+import type { VFile } from "vfile";
+import type { Transformer } from "unified";
+import type { Node } from "unist";
+import { visit, CONTINUE, SKIP } from "unist-util-visit";
+
+const versionedDocsPattern = `versioned_docs/version-([0-9]+\\.x)/`;
+
+export default function remarkVersionAlias(latestVersion: string): Transformer {
+  return (root: Root, vfile: VFile) => {
+    visit(root, (node: Node) => {
+      if (node.type != "mdxjsEsm") {
+        return CONTINUE;
+      }
+
+      // Only process import statements that import an identifier from a default
+      // export.
+      const esm = node as unknown as MdxjsEsm;
+      if (
+        !esm.data ||
+        !esm.data.estree ||
+        esm.data.estree.body.length !== 1 ||
+        esm.data.estree.body[0]["type"] != "ImportDeclaration" ||
+        esm.data.estree.body[0].specifiers.length !== 1 ||
+        esm.data.estree.body[0].specifiers[0].type != "ImportDefaultSpecifier"
+      ) {
+        return CONTINUE;
+      }
+
+      let version: string = latestVersion;
+      const versionedPathParts = vfile.path.match(versionedDocsPattern);
+      if (versionedPathParts) {
+        version = versionedPathParts[1];
+      }
+
+      const decl = esm.data.estree.body[0] as ImportDeclaration;
+
+      const newPath = (decl.source.value as string).replace(
+        "@version",
+        `@site/content/${version}`,
+      );
+
+      esm.value = `import ${esm.data.estree.body[0].specifiers[0].local.name} from '${newPath}'`;
+      decl.source = {
+        type: "Literal",
+        value: newPath,
+        raw: `"${newPath}"`,
+      };
+
+      return SKIP;
+    });
+  };
+}