From 27ff6de8b9cd74c3dc2b5caca7e2e1fa44ed01f4 Mon Sep 17 00:00:00 2001
From: samfreund <samf.236@proton.me>
Date: Sun, 28 Jun 2026 16:41:53 -0700
Subject: [PATCH 1/3] enforce code blocks using RLIs

---
 .remarkrc.mjs                                 |  8 +++++-
 .../contribution/methodsOfContributing.mdx    |  1 +
 src/content/docs/contribution/styleguide.mdx  |  1 +
 .../docs/intro-to-java/java-fundamentals.mdx  |  1 +
 src/plugins/remark-no-inline-code-fences.mjs  | 26 +++++++++++++++++++
 5 files changed, 36 insertions(+), 1 deletion(-)
 create mode 100644 src/plugins/remark-no-inline-code-fences.mjs

diff --git a/.remarkrc.mjs b/.remarkrc.mjs
index 4f8689e..175ab2f 100644
--- a/.remarkrc.mjs
+++ b/.remarkrc.mjs
@@ -1,7 +1,13 @@
 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';
 
 export default {
-    plugins: [remarkFrontmatter, remarkMdx, remarkPresetLintRecommended],
+    plugins: [
+        remarkFrontmatter,
+        remarkMdx,
+        remarkPresetLintRecommended,
+        remarkNoInlineCodeFences,
+    ],
 };
diff --git a/src/content/docs/contribution/methodsOfContributing.mdx b/src/content/docs/contribution/methodsOfContributing.mdx
index 0d04150..4d94e0e 100644
--- a/src/content/docs/contribution/methodsOfContributing.mdx
+++ b/src/content/docs/contribution/methodsOfContributing.mdx
@@ -12,6 +12,7 @@ import Aside from '../../../components/Aside.astro';
 FRCSoftware.org is just getting started, so the easiest way to propose work is by opening a GitHub issue in the main repository.
 Use this template in your issue:
 
+{/* rli:ignore */}
 ```
 Issue/content:
 Solution or Notes about the execution of the content:
diff --git a/src/content/docs/contribution/styleguide.mdx b/src/content/docs/contribution/styleguide.mdx
index 4ea0917..d10f32a 100644
--- a/src/content/docs/contribution/styleguide.mdx
+++ b/src/content/docs/contribution/styleguide.mdx
@@ -110,6 +110,7 @@ Enforced by `prettier-plugin-sentences-per-line`.
 
 Run all checks locally before pushing:
 
+{/* rli:ignore */}
 ```bash
 pnpm lint && pnpm format:check
 ```
diff --git a/src/content/docs/intro-to-java/java-fundamentals.mdx b/src/content/docs/intro-to-java/java-fundamentals.mdx
index 14abaa5..643ca84 100644
--- a/src/content/docs/intro-to-java/java-fundamentals.mdx
+++ b/src/content/docs/intro-to-java/java-fundamentals.mdx
@@ -33,6 +33,7 @@ This could be a variable that holds the temperature or a variable that holds the
 
 Variable declarations have the following syntax:
 
+{/* rli:ignore */}
 ```java
 Datatype name = value;
 ```
diff --git a/src/plugins/remark-no-inline-code-fences.mjs b/src/plugins/remark-no-inline-code-fences.mjs
new file mode 100644
index 0000000..6a90e4c
--- /dev/null
+++ b/src/plugins/remark-no-inline-code-fences.mjs
@@ -0,0 +1,26 @@
+import { visit } from 'unist-util-visit';
+
+const IGNORE_RE = /rli:\s*ignore/;
+
+export default function remarkNoInlineCodeFences() {
+    return (tree, file) => {
+        visit(tree, 'code', (node, index, parent) => {
+            if (index !== undefined && parent) {
+                const prev = parent.children[index - 1];
+                if (prev?.type === 'mdxFlowExpression' && IGNORE_RE.test(prev.value)) {
+                    return;
+                }
+            }
+
+            if (node.meta?.trim()) return;
+
+            if (node.value?.trim()) {
+                const msg = file.message(
+                    'Code fences must use the RLI system: ```language path/to/file#regionName',
+                    node,
+                );
+                msg.fatal = true;
+            }
+        });
+    };
+}

From 1d61b2ce555c5cfa6c683da42155935e5946f435 Mon Sep 17 00:00:00 2001
From: samfreund <samf.236@proton.me>
Date: Sun, 28 Jun 2026 17:20:06 -0700
Subject: [PATCH 2/3] fix unexpected any's

---
 eslint.config.mjs                              |  2 +-
 src/components/Slides.astro                    | 16 +++++++++++++---
 .../contribution/methodsOfContributing.mdx     |  1 +
 src/content/docs/contribution/styleguide.mdx   |  1 +
 .../docs/intro-to-java/java-fundamentals.mdx   |  1 +
 src/plugins/remark-code-region.ts              |  2 +-
 src/plugins/remark-image-attributes.ts         | 13 +++++++------
 src/plugins/remark-mdx-global-imports.ts       | 18 +++++++++++++-----
 src/plugins/remark-no-inline-code-fences.mjs   |  5 ++++-
 9 files changed, 42 insertions(+), 17 deletions(-)

diff --git a/eslint.config.mjs b/eslint.config.mjs
index 37230cb..085833e 100644
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -17,7 +17,7 @@ export default [
                 'warn',
                 { argsIgnorePattern: '^_' },
             ],
-            '@typescript-eslint/no-explicit-any': 'warn',
+            '@typescript-eslint/no-explicit-any': 'error',
         },
     },
 
diff --git a/src/components/Slides.astro b/src/components/Slides.astro
index 317b6b3..dd3270a 100644
--- a/src/components/Slides.astro
+++ b/src/components/Slides.astro
@@ -878,9 +878,19 @@ const slideId = `slides-${Math.random().toString(36).substring(2, 11)}`;
 </style>
 
 <script>
+    interface SlideClientData {
+        url: string;
+        type: string;
+        alt: string;
+        caption: string;
+        width: number | null;
+        height: number | null;
+        attrs: Record<string, string | undefined>;
+    }
+
     function initSlides() {
         document.querySelectorAll('.slides-component').forEach((component) => {
-            const slidesData = JSON.parse(
+            const slidesData: SlideClientData[] = JSON.parse(
                 component.getAttribute('data-slides') || '[]',
             );
             // Skip if already initialized
@@ -924,7 +934,7 @@ const slideId = `slides-${Math.random().toString(36).substring(2, 11)}`;
             let lightboxIndex = 0;
             let imagesLoaded = 0;
             const totalImages = slidesData.filter(
-                (s: any) => s.type === 'image',
+                (s) => s.type === 'image',
             ).length;
 
             // Track image dimensions for scaling
@@ -950,7 +960,7 @@ const slideId = `slides-${Math.random().toString(36).substring(2, 11)}`;
                 });
 
                 // Also consider YouTube videos as 16:9
-                slidesData.forEach((slide: any) => {
+                slidesData.forEach((slide) => {
                     if (slide.type === 'youtube') {
                         const youtubeAspectRatio = 16 / 9;
                         if (youtubeAspectRatio > widestAspectRatio) {
diff --git a/src/content/docs/contribution/methodsOfContributing.mdx b/src/content/docs/contribution/methodsOfContributing.mdx
index 4d94e0e..e685f9f 100644
--- a/src/content/docs/contribution/methodsOfContributing.mdx
+++ b/src/content/docs/contribution/methodsOfContributing.mdx
@@ -13,6 +13,7 @@ FRCSoftware.org is just getting started, so the easiest way to propose work is b
 Use this template in your issue:
 
 {/* rli:ignore */}
+
 ```
 Issue/content:
 Solution or Notes about the execution of the content:
diff --git a/src/content/docs/contribution/styleguide.mdx b/src/content/docs/contribution/styleguide.mdx
index d10f32a..4946d80 100644
--- a/src/content/docs/contribution/styleguide.mdx
+++ b/src/content/docs/contribution/styleguide.mdx
@@ -111,6 +111,7 @@ Enforced by `prettier-plugin-sentences-per-line`.
 Run all checks locally before pushing:
 
 {/* rli:ignore */}
+
 ```bash
 pnpm lint && pnpm format:check
 ```
diff --git a/src/content/docs/intro-to-java/java-fundamentals.mdx b/src/content/docs/intro-to-java/java-fundamentals.mdx
index 643ca84..ea4a3d0 100644
--- a/src/content/docs/intro-to-java/java-fundamentals.mdx
+++ b/src/content/docs/intro-to-java/java-fundamentals.mdx
@@ -34,6 +34,7 @@ This could be a variable that holds the temperature or a variable that holds the
 Variable declarations have the following syntax:
 
 {/* rli:ignore */}
+
 ```java
 Datatype name = value;
 ```
diff --git a/src/plugins/remark-code-region.ts b/src/plugins/remark-code-region.ts
index 11b7bf5..3f4a7cf 100644
--- a/src/plugins/remark-code-region.ts
+++ b/src/plugins/remark-code-region.ts
@@ -7,7 +7,7 @@ export default function remarkCodeRegion() {
     return (tree: Root) => {
         const examplesDir = resolve(process.cwd(), 'examples');
 
-        visit(tree, 'code', (node: any) => {
+        visit(tree, 'code', (node) => {
             const meta: string = node.meta || '';
 
             const token = meta.match(/^(\S+)/);
diff --git a/src/plugins/remark-image-attributes.ts b/src/plugins/remark-image-attributes.ts
index 3dd528d..1a846c2 100644
--- a/src/plugins/remark-image-attributes.ts
+++ b/src/plugins/remark-image-attributes.ts
@@ -14,21 +14,22 @@
  */
 
 import { visit } from 'unist-util-visit';
-import type { Root, Image } from 'mdast';
+import type { Root } from 'mdast';
 
-interface ImageNode extends Image {
+interface ImageNode {
+    url: string;
     data?: {
         hName?: string;
-        hProperties?: Record<string, any>;
+        hProperties?: Record<string, unknown>;
     };
 }
 
 interface ParentNode {
     type: string;
-    children: any[];
+    children: { type: string }[];
     data?: {
         hName?: string;
-        hProperties?: Record<string, any>;
+        hProperties?: Record<string, unknown>;
     };
 }
 
@@ -51,7 +52,7 @@ export function remarkImageAttributes() {
                     const child = children[i];
 
                     if (child.type === 'image') {
-                        const imageNode = child as ImageNode;
+                        const imageNode = child as unknown as ImageNode;
                         const url = imageNode.url;
 
                         // Check for hash in URL
diff --git a/src/plugins/remark-mdx-global-imports.ts b/src/plugins/remark-mdx-global-imports.ts
index 2984ef1..adad4fb 100644
--- a/src/plugins/remark-mdx-global-imports.ts
+++ b/src/plugins/remark-mdx-global-imports.ts
@@ -11,6 +11,16 @@
 import type { Root } from 'mdast';
 import type { VFile } from 'vfile';
 
+declare module 'mdast' {
+    interface RootContentMap {
+        mdxjsEsm: {
+            type: 'mdxjsEsm';
+            value: string;
+            data?: { estree?: unknown };
+        };
+    }
+}
+
 const GLOBAL_IMPORTS = [
     { name: 'ContentFigure', path: '@components/ContentFigure.astro' },
     { name: 'Aside', path: '@components/Aside.astro' },
@@ -54,10 +64,8 @@ export function remarkMdxGlobalImports() {
 
         const existingNames = new Set<string>();
         for (const node of tree.children) {
-            if ((node as any).type === 'mdxjsEsm') {
-                const match = (node as any).value?.match(
-                    /\bimport\s+(\w+)\s+from\b/,
-                );
+            if (node.type === 'mdxjsEsm') {
+                const match = node.value?.match(/\bimport\s+(\w+)\s+from\b/);
                 if (match) existingNames.add(match[1]);
             }
         }
@@ -67,7 +75,7 @@ export function remarkMdxGlobalImports() {
         ).map(({ name, path }) => makeImportNode(name, path));
 
         if (toInsert.length > 0) {
-            tree.children.unshift(...(toInsert as any[]));
+            tree.children.unshift(...toInsert);
         }
     };
 }
diff --git a/src/plugins/remark-no-inline-code-fences.mjs b/src/plugins/remark-no-inline-code-fences.mjs
index 6a90e4c..d123c98 100644
--- a/src/plugins/remark-no-inline-code-fences.mjs
+++ b/src/plugins/remark-no-inline-code-fences.mjs
@@ -7,7 +7,10 @@ export default function remarkNoInlineCodeFences() {
         visit(tree, 'code', (node, index, parent) => {
             if (index !== undefined && parent) {
                 const prev = parent.children[index - 1];
-                if (prev?.type === 'mdxFlowExpression' && IGNORE_RE.test(prev.value)) {
+                if (
+                    prev?.type === 'mdxFlowExpression' &&
+                    IGNORE_RE.test(prev.value)
+                ) {
                     return;
                 }
             }

From 1036f2c8244e26083fe91a0e079ca21ccfbc3693 Mon Sep 17 00:00:00 2001
From: samfreund <samf.236@proton.me>
Date: Sun, 28 Jun 2026 17:29:40 -0700
Subject: [PATCH 3/3] docs

---
 src/content/docs/contribution/styleguide.mdx | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/src/content/docs/contribution/styleguide.mdx b/src/content/docs/contribution/styleguide.mdx
index 4946d80..b1af1e4 100644
--- a/src/content/docs/contribution/styleguide.mdx
+++ b/src/content/docs/contribution/styleguide.mdx
@@ -117,3 +117,11 @@ pnpm lint && pnpm format:check
 ```
 
 If `pnpm format:check` fails, run `pnpm prettier --write .` to auto-fix.
+
+#### RLI (region-based code fences)
+
+Code fences must use the RLI system: ` ```language path/to/file#regionName ` with an empty body.
+The referenced file lives under `examples/` and uses `// [regionName]` / `// [/regionName]` markers to delimit the snippet.
+This keeps example code in real source files that are compiled and tested.
+
+If you need an inline code fence that doesn't reference an example file, suppress the rule by placing `{/* rli:ignore */}` on the line immediately before it.