Add hardware intro and resources overview pages

lint-staged.config.mjs

@@ -1,3 +1,5 @@
+import process from 'node:process';
+
 /** @type {import('lint-staged').Configuration} */
 export default {
     '**/*': (files) => `prettier --write --ignore-unknown ${files.join(' ')}`,
@@ -6,7 +8,7 @@ export default {
         `pnpm remark ${files.join(' ')} --ext mdx --frail --no-stdout --quiet`,
     ],
     'examples/**/*.{java,gradle}': () => [
-        `./examples/gradlew -p examples spotlessApply`,
+        `./examples/gradlew${process.platform === 'win32' ? '.bat' : ''} -p examples spotlessApply`,
     ],
     'src/data/glossary.ts': () => [
         'pnpm generate:glossary',

src/components/ContentCard.astro

@@ -0,0 +1,83 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends Omit<HTMLAttributes<'a'>, 'title'> {
+    title: string;
+    description?: string;
+    eyebrow?: string;
+    href: string;
+}
+
+const { title, description, eyebrow, href, ...attributes } = Astro.props;
+---
+
+<a class="content-card" href={href} {...attributes}>
+    {eyebrow && <p class="content-card-eyebrow">{eyebrow}</p>}
+    <h3>{title}</h3>
+    {description && <p class="content-card-description">{description}</p>}
+    <slot />
+    <span class="content-card-arrow" aria-hidden="true">→</span>
+</a>
+
+<style>
+    .content-card {
+        position: relative;
+        display: flex;
+        min-height: 11.5rem;
+        flex-direction: column;
+        padding: 1.2rem;
+        border: 1px solid var(--sl-color-gray-5);
+        border-radius: 0.5rem;
+        color: inherit;
+        text-decoration: none;
+        background: var(--sl-color-black);
+        transition:
+            border-color 160ms ease,
+            background-color 160ms ease;
+    }
+
+    .content-card:hover {
+        border-color: var(--accent-color);
+        background: color-mix(
+            in srgb,
+            var(--sl-color-black) 92%,
+            var(--accent-color)
+        );
+    }
+
+    .content-card-eyebrow {
+        margin: 0 2.25rem 0.7rem 0;
+        color: var(--sl-color-text-accent);
+        font-size: 0.76rem;
+        font-weight: 800;
+        letter-spacing: 0;
+        text-transform: uppercase;
+    }
+
+    .content-card h3 {
+        margin: 0 2.25rem 0.55rem 0;
+        color: var(--sl-color-white);
+        font-size: 1.35rem;
+        line-height: 1.2;
+    }
+
+    .content-card-description {
+        margin: 0;
+        color: var(--sl-color-gray-2);
+        line-height: 1.55;
+    }
+
+    .content-card-arrow {
+        position: absolute;
+        top: 1rem;
+        right: 1.15rem;
+        color: var(--sl-color-gray-3);
+        font-size: 1.35rem;
+        line-height: 1;
+        transition: color 160ms ease;
+    }
+
+    .content-card:hover .content-card-arrow {
+        color: var(--accent-color-hover);
+    }
+</style>

src/components/ContentTitleBar.astro

@@ -0,0 +1,48 @@
+---
+interface Props {
+    label?: string;
+    title: string;
+    description?: string;
+}
+
+const { label, title, description } = Astro.props;
+---
+
+<section class="content-titlebar">
+    {label && <p class="content-titlebar-label">{label}</p>}
+    <h2>{title}</h2>
+    {description && <p class="content-titlebar-description">{description}</p>}
+</section>
+
+<style>
+    .content-titlebar {
+        padding: 1.25rem 0 1.75rem;
+        margin-bottom: 1.5rem;
+        border-bottom: 1px solid var(--sl-color-gray-5);
+    }
+
+    .content-titlebar-label {
+        margin: 0 0 0.35rem;
+        color: var(--sl-color-text-accent);
+        font-size: 0.78rem;
+        font-weight: 800;
+        letter-spacing: 0;
+        text-transform: uppercase;
+    }
+
+    .content-titlebar h2 {
+        max-width: 18ch;
+        margin: 0;
+        color: var(--sl-color-white);
+        font-size: clamp(2.2rem, 4.8vw, 3.6rem);
+        line-height: 1;
+    }
+
+    .content-titlebar-description {
+        max-width: 46rem;
+        margin: 1rem 0 0;
+        color: var(--sl-color-gray-2);
+        font-size: 1.05rem;
+        line-height: 1.65;
+    }
+</style>

src/config/sidebarConfig.ts

@@ -313,9 +313,19 @@ export const sidebarSections: Record<string, SidebarSection[]> = {
         {
             label: 'Resources',
             items: [
-                { label: 'Overview', slug: 'resources' },
-                { label: 'Glossary', slug: 'resources/glossary' },
-                { label: 'Documentation', slug: 'resources/docs' },
+                { label: 'Overview', slug: 'resources/overview' },
+                {
+                    label: 'Glossary',
+                    slug: 'resources/glossary',
+                },
+                {
+                    label: 'Hardware',
+                    slug: 'resources/hardware-intro',
+                },
+                {
+                    label: 'Documentation',
+                    slug: 'resources/docs',
+                },
             ],
         },
     ],

src/content/docs/index.mdx

@@ -28,6 +28,12 @@ import HomeCard from '../../components/HomeCard.astro';
         icon="book"
         description="A guide for educators implementing the FRCSoftware.org Learning Course."
     />
+    <HomeCard
+        title="Other Resources"
+        href="/resources/overview"
+        icon="folder"
+        description="Besides the other content on the websie, we have a nice collection of resources (e.g. a glossary and hardware intro)."
+    />
     <HomeCard
         description="Help contribute! Since FRCSoftware.org is in such an early stage right now, we are in need of contributors."
         icon="wrench"

src/content/docs/resources/glossary.mdx

@@ -17,6 +17,10 @@ Continuous Integration: A software development practice where developers frequen
 GitHub is like Google Drive, but for code.
 It hosts git repositories and allows for improved collaboration on projects through pull requests and issues
 
+**Heading**
+
+The direction the robot is pointed, usually expressed as an angle in degrees
+
 **Limit Switch**
 
 Type of sensor that triggers when physically or magnetically hit.
@@ -30,6 +34,10 @@ An encoder that uses a receiver and a magnet to measure position and motion
 
 Power switch for the robot
 
+**Odometry**
+
+Using sensors on the robot to create an estimate of the pose of the robot on the field.
+
 **PDH**
 
 Power Distribution Hub

src/content/docs/resources/hardware-intro.mdx

@@ -0,0 +1,58 @@
+---
+title: Hardware Intro
+description: An introduction to hardware components for programmers
+---
+
+## Motors
+
+The difference between motors and motor controllers is motors are the physical actuators that spin a robot's mechanisms while motor controllers are the electronic interfaces that control the speed and direction of the motor.
+Most motor controllers also offer smart abilities like onboard PID controllers and integrated encoders.
+
+Motor controllers are used throughout the robot in many mechanisms:
+
+- Intakes: Spin wheels to collect game pieces
+- Shooters: Spin flywheels to launch game pieces
+- Indexers: Move game pieces through the robot
+- Arms/Elevators: Raise and lower mechanisms (often with position control)
+- Climbers: Extend or retract climbing mechanisms
+
+CAN motor controllers are available through vendors such as CTR Electronics (Talon FX) and REV Robotics (SPARK MAX).
+
+![TalonFX motor controller](../../../../public/hardware-intro/talonfx-motor-controller.webp#w=30)
+![SPARK MAX motor controller](../../../../public/hardware-intro/spark-max-motor-controller.webp#w=20)
+
+## Encoders
+
+Encoders are a sensor for measuring rotational motion.
+They are reliable and less-prone to noise and interference than analog devices (such as potentiometers) because they produce digital signals.
+They can return the position and velocity of a mechanism.
+Encoders come in a variety of form factors, and may be mounted at the end of a shaft or have a shaft run through them.
+Many motor controllers also have integrated encoders.
+Relative encoders track changes in position and reset to zero when the robot is turned off, while absolute encoders track exact, unique positions across a full rotation and retain this data even when powered off.
+
+## Beam Break
+
+A beam break detects if anything is between two points and returns a binary value.
+Beam breaks are typically [`DigitalInput`](https://github.wpilib.org/allwpilib/docs/2027/java/org/wpilib/hardware/discrete/DigitalInput.html)s and will return a `boolean`.
+Beam breaks can be used to detect when game pieces pass a specific point on a robot.
+
+## Limit Switch
+
+A limit switch detects if something is at a certain position or distance and returns a binary value.
+Limit switches are often used to restrict the range of motion of a joint or detect the presence of game pieces.
+While beam breaks and limit switches both detect the presence of an object, they differ in how they do this.
+Beam breaks detect whether a beam of light is being blocked by an object, while limit switches require physical contact with an object to detect it.
+
+## Inertial Measurement Units (IMUs)
+
+An IMU is a sensor that combines an accelerometer and a gyroscope.
+IMUs are used to measure a robot's orientation, rates of rotation, and acceleration and return these signals as a [`Rotation2d`](https://github.wpilib.org/allwpilib/docs/2027/java/org/wpilib/math/geometry/Rotation2d.html).
+They typically use degrees or radians for angular position (yaw/heading, pitch, and roll) and degrees per second or radians per second for angular velocity.
+They can be used for robot heading readings and odometry calculations.
+The most popular IMUs in FRC are navX2, Pigeon 2.0, and the onboard SystemCore IMU.
+Note that the onboard SystemCore IMU is new for 2027 and has not undergone significant successful testing.
+
+One important thing to note is that gyros measure rate rather than position.
+Position is inferred by repeatedly measuring the angular velocity and multiplying those values by the delta time between readings.
+Gyro angle measurements are always relative to some arbitrary zero angle determined by the angle of the gyro either when the robot was turned on or a zeroing method was called.
+They can have accumulated errors (called “drift”) that increase in magnitude the longer the gyro is used.

src/content/docs/resources/overview.mdx

@@ -0,0 +1,32 @@
+---
+title: Overview
+description: An overview of additional programming resources
+---
+
+import { CardGrid } from '@astrojs/starlight/components';
+import ContentCard from '../../../components/ContentCard.astro';
+import ContentTitleBar from '../../../components/ContentTitleBar.astro';
+
+<ContentTitleBar
+    label="Resources"
+    title="Enhance your programming workflow."
+    description="Resources to help improve your knowledge of terms and support your programming workflow."
+/>
+
+<CardGrid>
+
+<ContentCard
+    href="/resources/glossary/"
+    eyebrow="Reference"
+    title="Glossary"
+    description="A compiled list of acronyms, abbreviations, and definitions to help explain the language used across the site and community."
+/>
+
+<ContentCard
+    href="/resources/hardware-intro/"
+    eyebrow="Overview"
+    title="Hardware Intro"
+    description="An overview of common FRC hardware components for programmers."
+/>
+
+</CardGrid>

src/data/glossary.ts

@@ -99,6 +99,16 @@ export const glossaryTerms: GlossaryTerm[] = [
         definition:
             'GitHub is like Google Drive, but for code. It hosts git repositories and allows for improved collaboration on projects through pull requests and issues',
     },
+    {
+        term: 'Heading',
+        definition:
+            'The direction the robot is pointed, usually expressed as an angle in degrees',
+    },
+    {
+        term: 'Odometry',
+        definition:
+            'Using sensors on the robot to create an estimate of the pose of the robot on the field.',
+    },
 ];
 
 /**

src/starlightOverrides/Header.astro

@@ -13,7 +13,7 @@ const navLinks = [
     { href: '/learning-course/', label: 'Learning Course' },
     { href: '/educators-guide/introduction/', label: "Educator's Guide" },
     { href: '/best-practices/overview', label: 'Best Practices' },
-    { href: '/resources/docs', label: 'Other Resources' }, // TODO: update to '/resources/overview' after merging pr #104
+    { href: '/resources/overview', label: 'Other Resources' },
     { href: '/contribution/', label: 'Contribution' },
 ];