Change links to md style and enforce in CI

.remarkrc.mjs

@@ -2,12 +2,14 @@ import remarkPresetLintRecommended from 'remark-preset-lint-recommended';
 import remarkFrontmatter from 'remark-frontmatter';
 import remarkMdx from 'remark-mdx';
 import remarkNoInlineCodeFences from './src/plugins/remark-no-inline-code-fences.mjs';
+import remarkNoHtmlLinks from './src/plugins/remark-no-html-links.mjs';
 
 export default {
     plugins: [
         remarkFrontmatter,
         remarkMdx,
         remarkPresetLintRecommended,
         remarkNoInlineCodeFences,
+        remarkNoHtmlLinks,
     ],
 };

src/content/docs/learning-course/index.mdx

@@ -11,8 +11,8 @@ Welcome to FRCSoftware's learning course! The purpose of this course is to help
 The progression of the course moves from learning how to write Java to programming robots of increasing complexity.
 We start individual mechanisms of robots, using the FRC Kitbot, then move to more complex robots.
 
-Software in FRC is always changing! If you want to give feedback or have comments, feel free to do so through our <a href="https://github.com/frcsoftware/frcsoftware.org">Github </a>
-or <a href="discord.gg/uUugPrPZFs">Discord.</a>
+Software in FRC is always changing! If you want to give feedback or have comments, feel free to do so through our [Github](https://github.com/frcsoftware/frcsoftware.org)
+or [Discord.](discord.gg/uUugPrPZFs)
 
 <CourseSection
     title="Course Setup"
@@ -27,27 +27,17 @@ or <a href="discord.gg/uUugPrPZFs">Discord.</a>
     </p>
     <ul>
         <li>
-            {' '}
-            <a href="/learning-course/getting-started/required-tools/">
-                {' '}
-                Required Tools:{' '}
-            </a>{' '}
-            Download the tools needed for this learning course.{' '}
+            [Required Tools:](/learning-course/getting-started/required-tools/)
+            Download the tools needed for this learning course.
         </li>
         <li>
-            {' '}
-            <a href="/learning-course/getting-started/vscode-overview/">
-                {' '}
-                VS Code Overview:{' '}
-            </a>{' '}
-            Learn more about VS Code, the code editor used for this course.
+            [VS Code
+            Overview:](/learning-course/getting-started/vscode-overview/) Learn
+            more about VS Code, the code editor used for this course.
         </li>
         <li>
-            {' '}
-            <a href="/learning-course/getting-started/forking-and-cloning/">
-                {' '}
-                Forking and Cloning:{' '}
-            </a>
+            [Forking and
+            Cloning:](/learning-course/getting-started/forking-and-cloning/)
             Learn how to use git to fork and clone. This is important for
             accessing templates that are used throughout the course.
         </li>

src/content/docs/learning-course/stage0/conditionals.mdx

@@ -23,14 +23,11 @@ This section will cover three types of conditionals which are:
     There is also another type of conditional, called switch, but we will not be
     covering it in this section because it is not used as frequently in FRC
     programming. However, if you want to learn more about the switch statement,
-    you can learn more on w3school's page on{' '}
-    <a href="https://www.w3schools.com/java/java_switch.asp">
-        {' '}
-        which covers this type of conditional.{' '}
-    </a>
+    you can learn more on w3school's page [which covers this type of
+    conditional.](https://www.w3schools.com/java/java_switch.asp)
 </Aside>
 
-Like we mentioned earlier in <a href="/intro-to-java/java-fundamentals/"> Java Fundamentals </a>, all programming languages have syntax that needs to be followed.
+Like we mentioned earlier in [Java Fundamentals](/intro-to-java/java-fundamentals/), all programming languages have syntax that needs to be followed.
 One part of syntax is keywords.
 As a reminder, a keyword is a reserved word that the compiler uses to run the code.
 In Java, we use the following keywords for conditionals: `if`, `else if`, `else`

src/content/docs/learning-course/stage0/stage-overview.mdx

@@ -15,20 +15,6 @@ This will help ensure that you don’t miss any important information.
 
 This stage will cover the following topics
 
-<ul>
-    <li>
-        {' '}
-        <a href="\learning-course\stage0\java-fundamentals/">
-            {' '}
-            Java Fundamentals{' '}
-        </a>{' '}
-    </li>
-    <li>
-        {' '}
-        <a href="\learning-course\stage0\operators/"> Operators </a>{' '}
-    </li>
-    <li>
-        {' '}
-        <a href="\learning-course\stage0\conditionals/"> Conditionals </a>{' '}
-    </li>
-</ul>
+- [Java Fundamentals](\learning-course\intro-to-java\java-fundamentals)
+- [Operators](\learning-course\stage0\operators/)
+- [Conditionals](\learning-course\stage0\conditionals/)

src/content/docs/learning-course/stage1/stage-overview.mdx

@@ -20,5 +20,5 @@ Feel free to play around with the robot and control it in sim once you've finish
 
 This stage is composed of the following sub-stages:
 
-- <a href="../stage-1a/stage-overview">Stage 1A</a>
-- <a href="#">WIP</a>
+- [Stage 1A](../stage-1a/stage-overview)
+- [WIP](#)

src/content/docs/learning-course/stage1/stage1a/stage-overview.mdx

@@ -115,4 +115,4 @@ And that's all you need to know to get started! The rest of Stage 1A will cover
 
 This stage will cover the following topics:
 
-- <a href="#">WIP</a>
+- [WIP](#)

src/plugins/remark-no-html-links.mjs

@@ -0,0 +1,27 @@
+import { visit } from 'unist-util-visit';
+
+/**
+ * Forbid raw HTML/JSX anchor tags (`<a href="...">`) in favour of markdown
+ * link syntax (`[text](url)`). Keeps links consistent and portable.
+ */
+export default function remarkNoHtmlLinks() {
+    return (tree, file) => {
+        // MDX parses `<a>` into JSX element nodes; `remark-mdx` never emits raw
+        // `html` nodes, but check that type too for plain-markdown safety.
+        visit(
+            tree,
+            ['mdxJsxTextElement', 'mdxJsxFlowElement', 'html'],
+            (node) => {
+                const isAnchor =
+                    node.name === 'a' || /<a[\s/>]/i.test(node.value ?? '');
+                if (!isAnchor) return;
+
+                const msg = file.message(
+                    'Use markdown link syntax `[text](url)` instead of an HTML `<a>` tag.',
+                    node,
+                );
+                msg.fatal = true;
+            },
+        );
+    };
+}