From 0dfec5416f71840bce2171804337fb7d90cdf3d1 Mon Sep 17 00:00:00 2001 From: Andrew Haselton Date: Thu, 18 Jun 2026 23:39:03 -0400 Subject: [PATCH 1/9] WIP with Aside import error --- astro.config.mjs | 3 +- src/config/sidebarConfig.ts | 10 +++ .../educators-guide/introduction/index.mdx | 21 ++++++ src/content/docs/index.mdx | 6 ++ src/plugins/remark-mdx-global-imports.ts | 73 +++++++++++++++++++ src/starlightOverrides/Header.astro | 2 +- 6 files changed, 113 insertions(+), 2 deletions(-) create mode 100644 src/content/docs/educators-guide/introduction/index.mdx create mode 100644 src/plugins/remark-mdx-global-imports.ts diff --git a/astro.config.mjs b/astro.config.mjs index d17ec93..0697d6e 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -4,13 +4,14 @@ import remarkGlossary from './src/plugins/remark-glossary'; import remarkCenter from './src/plugins/remark-center'; import remarkFigure from './src/plugins/remark-figure'; import remarkImageAttributes from './src/plugins/remark-image-attributes'; +import { remarkMdxGlobalImports } from './src/plugins/remark-mdx-global-imports.ts'; export default defineConfig({ site: 'https://frcsoftware.org', prefetch: true, markdown: { - remarkPlugins: [remarkCenter, remarkFigure, remarkGlossary, remarkImageAttributes], + remarkPlugins: [remarkCenter, remarkFigure, remarkGlossary, remarkImageAttributes, remarkMdxGlobalImports], rehypePlugins: [], }, diff --git a/src/config/sidebarConfig.ts b/src/config/sidebarConfig.ts index 9deb55d..ecd5296 100644 --- a/src/config/sidebarConfig.ts +++ b/src/config/sidebarConfig.ts @@ -28,6 +28,16 @@ export const sidebarSections: Record = { }, ], + // Educator's Guide Section + '/educators-guide': [ + { + label: 'Educator\'s Guide', + items: [ + { label: 'Overview', slug: 'educators-guide' }, + ], + }, + ], + // Other Resources section (maps to /resources in content) '/other-resources': [ { diff --git a/src/content/docs/educators-guide/introduction/index.mdx b/src/content/docs/educators-guide/introduction/index.mdx new file mode 100644 index 0000000..7da2a72 --- /dev/null +++ b/src/content/docs/educators-guide/introduction/index.mdx @@ -0,0 +1,21 @@ +--- +title: Educator's Guide Overview +description: A guide for educators implementing the FRCSoftware.org Learning Course +template: splash +--- + +The FRCSoftware.org Learning Course is a self-paced, comprehensive program that teaches FRC robot programming and Java skills. +This guide is intended to help educators effectively implement the course while supporting their students throughout the learning process. +Designed for accessibility, the course requires minimal prior knowledge of physics or math, making it suitable for students from various background. +The emphasis is on building knowledge through consistent practice and review. + +## Course Usage + +The course is built for self-paced learning, where students can progress at their own speed. +It utilizes code and robot simulation, a tool standard throughout FRC programming, to enable students to see their work and results quickly and not require a specific robot, or any robot access. +It can either be used by students to self-tach or in a more classroom-esque setting where it's led by student programming leads or mentors. + + + diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index 775c380..c7ea27b 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -35,6 +35,12 @@ import HomeCard from '../../components/HomeCard.astro'; icon="book" description="Explains the main features of the website. Recommended to go through before the learning course." /> + { + if (!file.path?.endsWith('.mdx')) return; + + const existingNames = new Set(); + for (const node of tree.children) { + if (node.type === 'mdxjsEsm') { + const match = (node as any).value?.match(/\bimport\s+(\w+)\s+from\b/); + if (match) existingNames.add(match[1]); + } + } + + const toInsert = GLOBAL_IMPORTS + .filter(({ name }) => !existingNames.has(name)) + .map(({ name, path }) => makeImportNode(name, path)); + + if (toInsert.length > 0) { + tree.children.unshift(...(toInsert as any[])); + } + }; +} + +export default remarkMdxGlobalImports; \ No newline at end of file diff --git a/src/starlightOverrides/Header.astro b/src/starlightOverrides/Header.astro index e9f54b2..e2729c1 100644 --- a/src/starlightOverrides/Header.astro +++ b/src/starlightOverrides/Header.astro @@ -13,7 +13,7 @@ const navLinks = [ { href: "/feature-guide/", label: "Website Feature Guide" }, { href: "/getting-started/intro-to-prog/", label: "Getting Started" }, // { href: "/learning-course/", label: "Learning Course" }, -// { href: "/educators-guide/introduction/", label: "Educator's Guide" }, + { href: "/educators-guide/introduction/", label: "Educator's Guide" }, // { href: "/design-handbook/", label: "Design Handbook" }, // { href: "/mechanism-examples/", label: "Mechanism Examples" }, // { href: "/best-practices/", label: "Best Practices" }, From 3c6f97b6cac214500394fc5b2965b6898f68aac8 Mon Sep 17 00:00:00 2001 From: Andrew Haselton Date: Fri, 19 Jun 2026 00:25:19 -0400 Subject: [PATCH 2/9] Fix autoimport --- src/plugins/remark-mdx-global-imports.ts | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/plugins/remark-mdx-global-imports.ts b/src/plugins/remark-mdx-global-imports.ts index 7007c3e..a2a3acb 100644 --- a/src/plugins/remark-mdx-global-imports.ts +++ b/src/plugins/remark-mdx-global-imports.ts @@ -12,11 +12,11 @@ import type { Root } from 'mdast'; import type { VFile } from 'vfile'; const GLOBAL_IMPORTS = [ - { name: 'ContentFigure', path: '@components/content/ContentFigure.astro' }, - { name: 'Aside', path: '@components/content/Aside.astro' }, - { name: 'Slides', path: '@components/content/Slides.astro' }, - { name: 'LinkButton', path: '@components/content/LinkButton.astro' }, - { name: 'ImageTable', path: '@components/content/ImageTable.astro' }, + { name: 'ContentFigure', path: '@components/ContentFigure.astro' }, + { name: 'Aside', path: '@components/Aside.astro' }, + { name: 'Slides', path: '@components/Slides.astro' }, + { name: 'LinkButton', path: '@components/LinkButton.astro' }, +// { name: 'ImageTable', path: '@components/ImageTable.astro' }, ]; function makeImportNode(name: string, importPath: string) { From 154d191d517b6fe067146a2e82d5f05ee157d578 Mon Sep 17 00:00:00 2001 From: Andrew Haselton Date: Fri, 19 Jun 2026 00:25:27 -0400 Subject: [PATCH 3/9] Educator's Guide landing page --- .../educators-guide/introduction/index.mdx | 33 ++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/src/content/docs/educators-guide/introduction/index.mdx b/src/content/docs/educators-guide/introduction/index.mdx index 7da2a72..94f4daa 100644 --- a/src/content/docs/educators-guide/introduction/index.mdx +++ b/src/content/docs/educators-guide/introduction/index.mdx @@ -16,6 +16,37 @@ It utilizes code and robot simulation, a tool standard throughout FRC programmin It can either be used by students to self-tach or in a more classroom-esque setting where it's led by student programming leads or mentors. +The ideal setup is for educators to offload most of the curriculum (concepts, exercises, projects) to the website, freeing them up to give more individualized help and review to each student. +This is what may be called a “self-paced blended learning” approach, where preferably meeting time or class time is given for students to do the work at their own pace and for educators to review and catch mistakes as students are working through exercises and projects. + +This approach helps increase motivation and engagement, reduces gaps in knowledge, builds confidence, and helps make sure every student gets the support they need to learn. + +## Course Content + +While the initial Java content is taught via general exercises, the majority of the course is focused on teaching FRC programming skills through FRC-relevant exercises, where new skills and concepts are introduced in each project. +Each section has a bit of explanation on the concepts or skills being introduced in the exercise, with the exercises gradually decreasing in guidance to help students get more confident with writing software. + + + +The progression of the course moves from learning how to write Java to programming robots of increasing complexity, starting with individual mechanisms of robots and moving to full robots. +Students will then learn how to write a robot program from the ground-up, thinking about code structure and how to best write their code for a balance between speed and maintainability. + +Additionally, there are various reference sections that don't fall on the main Learning Course. +These cover topics that are relevant to FRC programming, such as swerve or vision, but aren't necessarily the core concepts that need to be taught to allow a student to meaningfully contribute in-season. +Generally, these topics are something only one student on a programming subteam would need to know, while the Learning Course focuses on the concepts every student will want to know to effectively contribute. + +The purpose of FRC software is to maximize the robot's capabilities in matches, working hand in hand with the robot's design and the team's strategy. +As such, this course places a focus on giving students the tools to write code efficienty and to maximize the use of time once the robot is complete. +This includes heavy utilization of simulation to develop and validate code, structuring code to be both quick to write and easy to make changes and maintain in-season, and giving students the tools to evaluate when certain control strategies may be necessary or whether a simpler, but easier, strategy is appropriate. + +There are infinitely many ways to structure a robot project or control a mechanism, but this course gives what its writers believe to be the best balance of simplicity, maintainability, and capability. +As such, how your team wrote code in the past isn't necessarily incorrect, it's just not how this course will be teaching. +The concepts taught in this course should be applicable to most teams' code structure. \ No newline at end of file From efa13c06c858cbc6fa3409dc7f7c2e6e6ed64418 Mon Sep 17 00:00:00 2001 From: Adriana Date: Wed, 17 Jun 2026 15:56:01 -0400 Subject: [PATCH 4/9] Start Educator's Guide landing page --- README.md | 4 ++-- src/config/sidebarConfig.ts | 10 +++++++++ .../educators-guide/introduction/index.mdx | 21 +++++++++++++++++++ src/content/docs/index.mdx | 6 ++++++ src/starlightOverrides/Header.astro | 2 +- 5 files changed, 40 insertions(+), 3 deletions(-) create mode 100644 src/content/docs/educators-guide/introduction/index.mdx diff --git a/README.md b/README.md index 1c251b3..7e35b28 100644 --- a/README.md +++ b/README.md @@ -304,8 +304,8 @@ For multiple images, use the Slides component instead. 1. **Clone the repository** ```bash - git clone https://github.com/frcsoftware/frcsoftware.github.io.git - cd frcsoftware.github.io + git clone https://github.com/frcsoftware/frcsoftware.org + cd frcsoftware.org ``` 2. **Install dependencies** diff --git a/src/config/sidebarConfig.ts b/src/config/sidebarConfig.ts index 9deb55d..ecd5296 100644 --- a/src/config/sidebarConfig.ts +++ b/src/config/sidebarConfig.ts @@ -28,6 +28,16 @@ export const sidebarSections: Record = { }, ], + // Educator's Guide Section + '/educators-guide': [ + { + label: 'Educator\'s Guide', + items: [ + { label: 'Overview', slug: 'educators-guide' }, + ], + }, + ], + // Other Resources section (maps to /resources in content) '/other-resources': [ { diff --git a/src/content/docs/educators-guide/introduction/index.mdx b/src/content/docs/educators-guide/introduction/index.mdx new file mode 100644 index 0000000..7da2a72 --- /dev/null +++ b/src/content/docs/educators-guide/introduction/index.mdx @@ -0,0 +1,21 @@ +--- +title: Educator's Guide Overview +description: A guide for educators implementing the FRCSoftware.org Learning Course +template: splash +--- + +The FRCSoftware.org Learning Course is a self-paced, comprehensive program that teaches FRC robot programming and Java skills. +This guide is intended to help educators effectively implement the course while supporting their students throughout the learning process. +Designed for accessibility, the course requires minimal prior knowledge of physics or math, making it suitable for students from various background. +The emphasis is on building knowledge through consistent practice and review. + +## Course Usage + +The course is built for self-paced learning, where students can progress at their own speed. +It utilizes code and robot simulation, a tool standard throughout FRC programming, to enable students to see their work and results quickly and not require a specific robot, or any robot access. +It can either be used by students to self-tach or in a more classroom-esque setting where it's led by student programming leads or mentors. + + + diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index 775c380..c7ea27b 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -35,6 +35,12 @@ import HomeCard from '../../components/HomeCard.astro'; icon="book" description="Explains the main features of the website. Recommended to go through before the learning course." /> + Date: Fri, 19 Jun 2026 19:42:25 -0400 Subject: [PATCH 5/9] Start remark autoimport --- astro.config.mjs | 3 +- src/plugins/remark-mdx-global-imports.ts | 73 ++++++++++++++++++++++++ 2 files changed, 75 insertions(+), 1 deletion(-) create mode 100644 src/plugins/remark-mdx-global-imports.ts diff --git a/astro.config.mjs b/astro.config.mjs index d17ec93..0697d6e 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -4,13 +4,14 @@ import remarkGlossary from './src/plugins/remark-glossary'; import remarkCenter from './src/plugins/remark-center'; import remarkFigure from './src/plugins/remark-figure'; import remarkImageAttributes from './src/plugins/remark-image-attributes'; +import { remarkMdxGlobalImports } from './src/plugins/remark-mdx-global-imports.ts'; export default defineConfig({ site: 'https://frcsoftware.org', prefetch: true, markdown: { - remarkPlugins: [remarkCenter, remarkFigure, remarkGlossary, remarkImageAttributes], + remarkPlugins: [remarkCenter, remarkFigure, remarkGlossary, remarkImageAttributes, remarkMdxGlobalImports], rehypePlugins: [], }, diff --git a/src/plugins/remark-mdx-global-imports.ts b/src/plugins/remark-mdx-global-imports.ts new file mode 100644 index 0000000..7007c3e --- /dev/null +++ b/src/plugins/remark-mdx-global-imports.ts @@ -0,0 +1,73 @@ +/** + * Remark plugin that auto-injects common component imports into every MDX file. + * Contributors no longer need to manually import ContentFigure, Aside, Slides, + * or LinkButton. They are available in all MDX pages automatically. + * + * Runs in the remark pipeline (same as remarkCenter and remarkGlossary), which + * Astro applies to all MDX files. Skips injection for any component already + * imported to avoid duplicate identifier errors. No-ops on plain .md files. + */ + +import type { Root } from 'mdast'; +import type { VFile } from 'vfile'; + +const GLOBAL_IMPORTS = [ + { name: 'ContentFigure', path: '@components/content/ContentFigure.astro' }, + { name: 'Aside', path: '@components/content/Aside.astro' }, + { name: 'Slides', path: '@components/content/Slides.astro' }, + { name: 'LinkButton', path: '@components/content/LinkButton.astro' }, + { name: 'ImageTable', path: '@components/content/ImageTable.astro' }, +]; + +function makeImportNode(name: string, importPath: string) { + return { + type: 'mdxjsEsm' as const, + value: `import ${name} from '${importPath}';`, + data: { + estree: { + type: 'Program', + body: [ + { + type: 'ImportDeclaration', + specifiers: [ + { + type: 'ImportDefaultSpecifier', + local: { type: 'Identifier', name }, + }, + ], + source: { + type: 'Literal', + value: importPath, + raw: `'${importPath}'`, + }, + }, + ], + sourceType: 'module', + }, + }, + }; +} + +export function remarkMdxGlobalImports() { + return (tree: Root, file: VFile) => { + if (!file.path?.endsWith('.mdx')) return; + + const existingNames = new Set(); + for (const node of tree.children) { + if (node.type === 'mdxjsEsm') { + const match = (node as any).value?.match(/\bimport\s+(\w+)\s+from\b/); + if (match) existingNames.add(match[1]); + } + } + + const toInsert = GLOBAL_IMPORTS + .filter(({ name }) => !existingNames.has(name)) + .map(({ name, path }) => makeImportNode(name, path)); + + if (toInsert.length > 0) { + tree.children.unshift(...(toInsert as any[])); + } + }; +} + +export default remarkMdxGlobalImports; \ No newline at end of file From 9bd32adf30a9f9987f6aadc948bdc749de37f422 Mon Sep 17 00:00:00 2001 From: Andrew Haselton Date: Fri, 19 Jun 2026 00:25:19 -0400 Subject: [PATCH 6/9] Fix autoimport --- src/plugins/remark-mdx-global-imports.ts | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/plugins/remark-mdx-global-imports.ts b/src/plugins/remark-mdx-global-imports.ts index 7007c3e..a2a3acb 100644 --- a/src/plugins/remark-mdx-global-imports.ts +++ b/src/plugins/remark-mdx-global-imports.ts @@ -12,11 +12,11 @@ import type { Root } from 'mdast'; import type { VFile } from 'vfile'; const GLOBAL_IMPORTS = [ - { name: 'ContentFigure', path: '@components/content/ContentFigure.astro' }, - { name: 'Aside', path: '@components/content/Aside.astro' }, - { name: 'Slides', path: '@components/content/Slides.astro' }, - { name: 'LinkButton', path: '@components/content/LinkButton.astro' }, - { name: 'ImageTable', path: '@components/content/ImageTable.astro' }, + { name: 'ContentFigure', path: '@components/ContentFigure.astro' }, + { name: 'Aside', path: '@components/Aside.astro' }, + { name: 'Slides', path: '@components/Slides.astro' }, + { name: 'LinkButton', path: '@components/LinkButton.astro' }, +// { name: 'ImageTable', path: '@components/ImageTable.astro' }, ]; function makeImportNode(name: string, importPath: string) { From 8c12770ea919cebe366093661af5fd0bc6a64153 Mon Sep 17 00:00:00 2001 From: Andrew Haselton Date: Fri, 19 Jun 2026 00:25:27 -0400 Subject: [PATCH 7/9] Educator's Guide landing page --- .../educators-guide/introduction/index.mdx | 33 ++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/src/content/docs/educators-guide/introduction/index.mdx b/src/content/docs/educators-guide/introduction/index.mdx index 7da2a72..94f4daa 100644 --- a/src/content/docs/educators-guide/introduction/index.mdx +++ b/src/content/docs/educators-guide/introduction/index.mdx @@ -16,6 +16,37 @@ It utilizes code and robot simulation, a tool standard throughout FRC programmin It can either be used by students to self-tach or in a more classroom-esque setting where it's led by student programming leads or mentors. +The ideal setup is for educators to offload most of the curriculum (concepts, exercises, projects) to the website, freeing them up to give more individualized help and review to each student. +This is what may be called a “self-paced blended learning” approach, where preferably meeting time or class time is given for students to do the work at their own pace and for educators to review and catch mistakes as students are working through exercises and projects. + +This approach helps increase motivation and engagement, reduces gaps in knowledge, builds confidence, and helps make sure every student gets the support they need to learn. + +## Course Content + +While the initial Java content is taught via general exercises, the majority of the course is focused on teaching FRC programming skills through FRC-relevant exercises, where new skills and concepts are introduced in each project. +Each section has a bit of explanation on the concepts or skills being introduced in the exercise, with the exercises gradually decreasing in guidance to help students get more confident with writing software. + + + +The progression of the course moves from learning how to write Java to programming robots of increasing complexity, starting with individual mechanisms of robots and moving to full robots. +Students will then learn how to write a robot program from the ground-up, thinking about code structure and how to best write their code for a balance between speed and maintainability. + +Additionally, there are various reference sections that don't fall on the main Learning Course. +These cover topics that are relevant to FRC programming, such as swerve or vision, but aren't necessarily the core concepts that need to be taught to allow a student to meaningfully contribute in-season. +Generally, these topics are something only one student on a programming subteam would need to know, while the Learning Course focuses on the concepts every student will want to know to effectively contribute. + +The purpose of FRC software is to maximize the robot's capabilities in matches, working hand in hand with the robot's design and the team's strategy. +As such, this course places a focus on giving students the tools to write code efficienty and to maximize the use of time once the robot is complete. +This includes heavy utilization of simulation to develop and validate code, structuring code to be both quick to write and easy to make changes and maintain in-season, and giving students the tools to evaluate when certain control strategies may be necessary or whether a simpler, but easier, strategy is appropriate. + +There are infinitely many ways to structure a robot project or control a mechanism, but this course gives what its writers believe to be the best balance of simplicity, maintainability, and capability. +As such, how your team wrote code in the past isn't necessarily incorrect, it's just not how this course will be teaching. +The concepts taught in this course should be applicable to most teams' code structure. \ No newline at end of file From 3219139317eff27d3373107d2bcd9c9c6bf141dc Mon Sep 17 00:00:00 2001 From: Andrew Haselton Date: Fri, 19 Jun 2026 20:12:11 -0400 Subject: [PATCH 8/9] Educator's Guide landing page --- src/config/sidebarConfig.ts | 10 ++++ .../educators-guide/introduction/index.mdx | 52 +++++++++++++++++++ src/content/docs/index.mdx | 6 +++ src/starlightOverrides/Header.astro | 2 +- 4 files changed, 69 insertions(+), 1 deletion(-) create mode 100644 src/content/docs/educators-guide/introduction/index.mdx diff --git a/src/config/sidebarConfig.ts b/src/config/sidebarConfig.ts index 9deb55d..ecd5296 100644 --- a/src/config/sidebarConfig.ts +++ b/src/config/sidebarConfig.ts @@ -28,6 +28,16 @@ export const sidebarSections: Record = { }, ], + // Educator's Guide Section + '/educators-guide': [ + { + label: 'Educator\'s Guide', + items: [ + { label: 'Overview', slug: 'educators-guide' }, + ], + }, + ], + // Other Resources section (maps to /resources in content) '/other-resources': [ { diff --git a/src/content/docs/educators-guide/introduction/index.mdx b/src/content/docs/educators-guide/introduction/index.mdx new file mode 100644 index 0000000..94f4daa --- /dev/null +++ b/src/content/docs/educators-guide/introduction/index.mdx @@ -0,0 +1,52 @@ +--- +title: Educator's Guide Overview +description: A guide for educators implementing the FRCSoftware.org Learning Course +template: splash +--- + +The FRCSoftware.org Learning Course is a self-paced, comprehensive program that teaches FRC robot programming and Java skills. +This guide is intended to help educators effectively implement the course while supporting their students throughout the learning process. +Designed for accessibility, the course requires minimal prior knowledge of physics or math, making it suitable for students from various background. +The emphasis is on building knowledge through consistent practice and review. + +## Course Usage + +The course is built for self-paced learning, where students can progress at their own speed. +It utilizes code and robot simulation, a tool standard throughout FRC programming, to enable students to see their work and results quickly and not require a specific robot, or any robot access. +It can either be used by students to self-tach or in a more classroom-esque setting where it's led by student programming leads or mentors. + + + +The ideal setup is for educators to offload most of the curriculum (concepts, exercises, projects) to the website, freeing them up to give more individualized help and review to each student. +This is what may be called a “self-paced blended learning” approach, where preferably meeting time or class time is given for students to do the work at their own pace and for educators to review and catch mistakes as students are working through exercises and projects. + +This approach helps increase motivation and engagement, reduces gaps in knowledge, builds confidence, and helps make sure every student gets the support they need to learn. + +## Course Content + +While the initial Java content is taught via general exercises, the majority of the course is focused on teaching FRC programming skills through FRC-relevant exercises, where new skills and concepts are introduced in each project. +Each section has a bit of explanation on the concepts or skills being introduced in the exercise, with the exercises gradually decreasing in guidance to help students get more confident with writing software. + + + +The progression of the course moves from learning how to write Java to programming robots of increasing complexity, starting with individual mechanisms of robots and moving to full robots. +Students will then learn how to write a robot program from the ground-up, thinking about code structure and how to best write their code for a balance between speed and maintainability. + +Additionally, there are various reference sections that don't fall on the main Learning Course. +These cover topics that are relevant to FRC programming, such as swerve or vision, but aren't necessarily the core concepts that need to be taught to allow a student to meaningfully contribute in-season. +Generally, these topics are something only one student on a programming subteam would need to know, while the Learning Course focuses on the concepts every student will want to know to effectively contribute. + +The purpose of FRC software is to maximize the robot's capabilities in matches, working hand in hand with the robot's design and the team's strategy. +As such, this course places a focus on giving students the tools to write code efficienty and to maximize the use of time once the robot is complete. +This includes heavy utilization of simulation to develop and validate code, structuring code to be both quick to write and easy to make changes and maintain in-season, and giving students the tools to evaluate when certain control strategies may be necessary or whether a simpler, but easier, strategy is appropriate. + +There are infinitely many ways to structure a robot project or control a mechanism, but this course gives what its writers believe to be the best balance of simplicity, maintainability, and capability. +As such, how your team wrote code in the past isn't necessarily incorrect, it's just not how this course will be teaching. +The concepts taught in this course should be applicable to most teams' code structure. \ No newline at end of file diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index 775c380..c7ea27b 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -35,6 +35,12 @@ import HomeCard from '../../components/HomeCard.astro'; icon="book" description="Explains the main features of the website. Recommended to go through before the learning course." /> + Date: Mon, 22 Jun 2026 21:29:17 -0400 Subject: [PATCH 9/9] Finish Educator's Guide intro, add blank stage pages --- src/config/sidebarConfig.ts | 15 ++++++-- .../educators-guide/introduction/index.mdx | 5 +-- .../introduction/preparation.mdx | 25 ++++++++++++ .../introduction/the-stages.mdx | 38 +++++++++++++++++++ .../docs/educators-guide/stage0/index.mdx | 8 ++++ .../docs/educators-guide/stage1/index.mdx | 6 +++ .../docs/educators-guide/stage1/stage1a.mdx | 6 +++ .../docs/educators-guide/stage1/stage1b.mdx | 6 +++ .../docs/educators-guide/stage2/index.mdx | 6 +++ 9 files changed, 109 insertions(+), 6 deletions(-) create mode 100644 src/content/docs/educators-guide/introduction/preparation.mdx create mode 100644 src/content/docs/educators-guide/introduction/the-stages.mdx create mode 100644 src/content/docs/educators-guide/stage0/index.mdx create mode 100644 src/content/docs/educators-guide/stage1/index.mdx create mode 100644 src/content/docs/educators-guide/stage1/stage1a.mdx create mode 100644 src/content/docs/educators-guide/stage1/stage1b.mdx create mode 100644 src/content/docs/educators-guide/stage2/index.mdx diff --git a/src/config/sidebarConfig.ts b/src/config/sidebarConfig.ts index ecd5296..4db6912 100644 --- a/src/config/sidebarConfig.ts +++ b/src/config/sidebarConfig.ts @@ -28,12 +28,21 @@ export const sidebarSections: Record = { }, ], - // Educator's Guide Section + // Educator's Guide section '/educators-guide': [ { - label: 'Educator\'s Guide', + label: "Educator's Guide", items: [ - { label: 'Overview', slug: 'educators-guide' }, + { label: 'Introduction', slug: 'educators-guide/introduction' }, + { label: 'The Stages', slug: 'educators-guide/introduction/the-stages' }, + { label: 'Preparing Yourself', slug: 'educators-guide/introduction/preparation' }, + { label: 'Stage 0', slug: 'educators-guide/stage0' }, + { label: 'Stage 1', collapsed: true, items: [ + { label: 'Overview', slug: 'educators-guide/stage1' }, + { label: 'Stage 1A', slug: 'educators-guide/stage1/stage1a' }, + { label: 'Stage 1B', slug: 'educators-guide/stage1/stage1b' }, + ]}, + { label: 'Stage 2', slug: 'educators-guide/stage2' }, ], }, ], diff --git a/src/content/docs/educators-guide/introduction/index.mdx b/src/content/docs/educators-guide/introduction/index.mdx index 94f4daa..315834f 100644 --- a/src/content/docs/educators-guide/introduction/index.mdx +++ b/src/content/docs/educators-guide/introduction/index.mdx @@ -1,12 +1,11 @@ --- title: Educator's Guide Overview description: A guide for educators implementing the FRCSoftware.org Learning Course -template: splash --- The FRCSoftware.org Learning Course is a self-paced, comprehensive program that teaches FRC robot programming and Java skills. This guide is intended to help educators effectively implement the course while supporting their students throughout the learning process. -Designed for accessibility, the course requires minimal prior knowledge of physics or math, making it suitable for students from various background. +Designed for accessibility, the course requires minimal prior knowledge of physics or math, making it suitable for students from various backgrounds. The emphasis is on building knowledge through consistent practice and review. ## Course Usage @@ -44,7 +43,7 @@ These cover topics that are relevant to FRC programming, such as swerve or visio Generally, these topics are something only one student on a programming subteam would need to know, while the Learning Course focuses on the concepts every student will want to know to effectively contribute. The purpose of FRC software is to maximize the robot's capabilities in matches, working hand in hand with the robot's design and the team's strategy. -As such, this course places a focus on giving students the tools to write code efficienty and to maximize the use of time once the robot is complete. +As such, this course places a focus on giving students the tools to write code efficiently and to maximize the use of time once the robot is complete. This includes heavy utilization of simulation to develop and validate code, structuring code to be both quick to write and easy to make changes and maintain in-season, and giving students the tools to evaluate when certain control strategies may be necessary or whether a simpler, but easier, strategy is appropriate. There are infinitely many ways to structure a robot project or control a mechanism, but this course gives what its writers believe to be the best balance of simplicity, maintainability, and capability. diff --git a/src/content/docs/educators-guide/introduction/preparation.mdx b/src/content/docs/educators-guide/introduction/preparation.mdx new file mode 100644 index 0000000..445323d --- /dev/null +++ b/src/content/docs/educators-guide/introduction/preparation.mdx @@ -0,0 +1,25 @@ +--- +title: Preparation +description: A guide for educators to prepare themselves to deliver the Learning Course to students. +--- + +Before using the FRCSoftware.org Learning Course to teach your students, make sure you have an adequate understanding of the concepts covered. +The best wya to do this is to go through the course yourself; however, the level of involvement with which you do so is dependent on your previous knowledge. +If you're new to FRC programming or Java, we recommend going pretty deep through the course as much as you can, at least so you're ahead of the students you're helping guide. +If you're pretty experienced with Java and FRC programming, you might just go through the Educator's Guide to get a complete overview of the course and caught up to date with practice. + + + +In particular, familiarizing yourself with the development environment, tools, and git is going to be particularly helpful to ensure that your students can focus on the code itself. +Additionally, having such software on your own computer will allow you to demonstrate things for students without impacting their own code. + +## Final Advice + +1. Remember that is is ok for students to be at wildly different sections of the course. +2. Even if a student just gets through stage 1, they would have enough knowledge to be somewhat helpful and easy to guide during build season. +The more sections they complete, the more autonomous they should be as a developer, making them easier to lead to complete a task. +3. When helping students, make sure ot not handhold them too much. +If you're in a situation where you can get the student to solve a problem by asking some guiding questions, do that. diff --git a/src/content/docs/educators-guide/introduction/the-stages.mdx b/src/content/docs/educators-guide/introduction/the-stages.mdx new file mode 100644 index 0000000..476b646 --- /dev/null +++ b/src/content/docs/educators-guide/introduction/the-stages.mdx @@ -0,0 +1,38 @@ +--- +title: The Stages +description: An explanation FRCSoftware.org Learning Course stages for educators +--- + +The course progressively builds complexity while reinforcing core concepts of good software development practices, controls fundamentals, and code organization. +It starts with basic code to control a 2026 kitbot and progresses through more complex robots and mechanisms. + +## Stage Section Overview + +**Stage 0: Java Fundamentals** + - Sets up students with the development environment and required tooling + - Teaches students the Java concepts necessary for FRC software + +**Stage 1a: Basic FRC Programming** + - Introduces students to many of the development tools which will be used throughout the course and for general FRC development + - Provides an overview of FRC electronics + - Introduces students to the 2026 Kitbot, which will be utilized throughout Stage 1 + - Teaches the basics of FRC motor controller and gamepad interaction + - Students will have a functional teleoperated kitbot program and a basic auto + +**Stage 1b: Introduction to Command-Based Programming** + - Introduces command-based programming + - Introduces logging and telemetry + - Introduces the concept of code structure and working with multiple files + - Covers the basics of PID control when applied to simple autonomous driving + - Students will have a functional teleoperated kitbot program and a more advanced auto + +**Stage 2: 2025 Robot** + - Introduces feedforward control and mechanism dynamics + - Provides techniques for additional teleoperated automation + - Students will write entire `Mechanism`s on their own + - Introduces commands v3 state machines + - Discusses various code structure and organization choices that will have to be made in any given robot project + - Covers one technique to prevent mechanisms from colliding with the rest of the robot + +Additionally, all stages will naturally include a significant amount of debugging experience as students write their code. +Debugging is a critical skill that all students should know as, inevitably, some code won't work as expected on the first try. \ No newline at end of file diff --git a/src/content/docs/educators-guide/stage0/index.mdx b/src/content/docs/educators-guide/stage0/index.mdx new file mode 100644 index 0000000..acc7b8b --- /dev/null +++ b/src/content/docs/educators-guide/stage0/index.mdx @@ -0,0 +1,8 @@ +--- +title: "Stage 0: Java Fundamentals" +description: An overview of Stage 0 for educators +--- + +## Overview + +WIP diff --git a/src/content/docs/educators-guide/stage1/index.mdx b/src/content/docs/educators-guide/stage1/index.mdx new file mode 100644 index 0000000..fde92ab --- /dev/null +++ b/src/content/docs/educators-guide/stage1/index.mdx @@ -0,0 +1,6 @@ +--- +title: Stage 1 Overview +description: An overview of Stage 1 for educators +--- + +WIP \ No newline at end of file diff --git a/src/content/docs/educators-guide/stage1/stage1a.mdx b/src/content/docs/educators-guide/stage1/stage1a.mdx new file mode 100644 index 0000000..5413955 --- /dev/null +++ b/src/content/docs/educators-guide/stage1/stage1a.mdx @@ -0,0 +1,6 @@ +--- +title: "Stage 1A: Basic FRC Programming" +description: An overview of Stage 1A for educators +--- + +WIP \ No newline at end of file diff --git a/src/content/docs/educators-guide/stage1/stage1b.mdx b/src/content/docs/educators-guide/stage1/stage1b.mdx new file mode 100644 index 0000000..ee67692 --- /dev/null +++ b/src/content/docs/educators-guide/stage1/stage1b.mdx @@ -0,0 +1,6 @@ +--- +title: "Stage 1B: Introduction to Command-Based Programming" +description: An overview of Stage 1B for educators +--- + +WIP \ No newline at end of file diff --git a/src/content/docs/educators-guide/stage2/index.mdx b/src/content/docs/educators-guide/stage2/index.mdx new file mode 100644 index 0000000..105aff3 --- /dev/null +++ b/src/content/docs/educators-guide/stage2/index.mdx @@ -0,0 +1,6 @@ +--- +title: Stage 2 Overview +description: An overview of Stage 2 for educators +--- + +WIP \ No newline at end of file