Updated contributor docs with info about adding language.mdx (#2955)

Author: AndreasArvidsson

packages/cursorless-org-docs/docusaurus.config.mts

@@ -1,14 +1,19 @@
 import type { Config } from "@docusaurus/types";
 import type { Root } from "mdast";
-import { dirname, relative, resolve } from "path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { dirname, extname, relative, resolve } from "path";
 import { themes } from "prism-react-renderer";
 import type { Transformer } from "unified";
 import { visit } from "unist-util-visit";
-import { createRequire } from "node:module";
-import { fileURLToPath } from "node:url";
 
 const require = createRequire(import.meta.url);
 
+const docsRelative = "packages/cursorless-org-docs/src/docs/";
+const userRelative = docsRelative + "user";
+const contributingRelative = docsRelative + "contributing";
+const repoLink = "https://github.com/cursorless-dev/cursorless/tree/main/";
+
 /**
  * Files within /docs reference repository directories
  * and files outside of that folder. They are not served
@@ -43,23 +48,40 @@ function remarkPluginFixLinksToRepositoryArtifacts(): Transformer<Root> {
       );
       const artifact = resolve(file.dirname!, url);
       const artifactRelative = relative(repoRoot, artifact).replace(/\\/g, "/");
+      const fileRelative = relative(repoRoot, file.path).replace(/\\/g, "/");
 
-      // We host all files under docs, will resolve as a relative link
-      if (
-        artifactRelative.startsWith("packages/cursorless-org-docs/src/docs/")
-      ) {
+      // We host all files under docs. Will resolve as a relative link, but
+      // relative links pointing to a folder passing between user and
+      // contributing are not resolved correctly by docusaurus so we need to
+      // rewrite them.
+      if (artifactRelative.startsWith(docsRelative)) {
+        if (
+          isFolder(url) &&
+          passingBetweenUserAndContributing(fileRelative, artifactRelative)
+        ) {
+          node.url = "/docs/" + artifactRelative.slice(docsRelative.length);
+        }
         return;
       }
 
-      const repoLink =
-        "https://github.com/cursorless-dev/cursorless/tree/main/";
-      const linkToRepositoryArtifact = repoLink.concat(artifactRelative);
-
-      node.url = linkToRepositoryArtifact;
+      node.url = repoLink + artifactRelative;
     });
   };
 }
 
+function isFolder(url: string) {
+  return !extname(url);
+}
+
+function passingBetweenUserAndContributing(
+  fileRelative: string,
+  artifactRelative: string,
+): boolean {
+  return fileRelative.startsWith(userRelative)
+    ? !artifactRelative.startsWith(userRelative)
+    : !artifactRelative.startsWith(contributingRelative);
+}
+
 const config: Config = {
   title: "Cursorless",
   tagline: "Structural voice coding at the speed of thought",
@@ -99,6 +121,7 @@ const config: Config = {
   ],
   onBrokenLinks: "throw",
   onBrokenMarkdownLinks: "throw",
+  onBrokenAnchors: "throw",
   trailingSlash: true,
 
   presets: [

packages/cursorless-org-docs/src/docs/contributing/adding-a-new-language.md

@@ -38,3 +38,15 @@ You can file a PR with just these changes to get the ball rolling.
 ## 4. Define your language's scopes
 
 Follow the instructions in [Adding a new scope](./adding-a-new-scope.md) to define the scopes for your language. Note that you can file a PR for each added scope, or do a couple at a time, but it's best _**not**_ to do them all at once, as smaller PRs make the review process easier.
+
+## 5. Document your language
+
+Create a `.mdx` file in [`languages`](../user/languages) with the `Language` react component. The file should be named after your language, eg `java.mdx`
+
+```md
+import { Language } from "./components/Language";
+
+# Java
+
+<Language languageId="java"></Language>
+```

packages/cursorless-org-docs/src/docs/contributing/architecture/neovim-test-infrastructure.md

@@ -300,7 +300,7 @@ cursorless.nvim/.busted
 ### Running lua unit tests
 
 Many of the cursorless.nvim lua functions are run in order to complete Cursorless actions and so are already
-indirectly tested by the tests described in the [previous section](#3-cursorless-tests-for-neovim). Nevertheless, we run
+indirectly tested by the tests described in the [previous section](#running-neovim-tests-locally). Nevertheless, we run
 more specific unit tests in order to give better visibility into exactly which functions are failing.
 The [busted](https://github.com/lunarmodules/busted) framework is used to test lua functions defined in cursorless.nvim.
 This relies on a `cursorless.nvim/.busted` file which directs busted to use a lua interpreter and test specifications files: