About These Docs

Purpose of the docs

These documentation pages are designed for FTC (First Tech Challenge) teams who want to understand and implement their own state machine library. The docs cover the Infinite State Machine (ISM) library, which consists of three main components:

  • StateMachine — The top-level controller that manages states and transitions
  • StateSequence — An ordered list of steps that run sequentially without blocking
  • StateTask — A single unit of behavior with enter, update, and exit hooks

The documentation is split into two complementary tutorials:

  • State machine tutorial — A design-first approach: preplanning (game plan → states → transitions), UML diagrams, concepts, and high-level steps. This tutorial focuses on what to build and why, before diving into code.
  • Library tutorial — Full implementation details: complete code for Task, Sequence, and Machine in both Java and Kotlin, with explanations of how each piece works. This tutorial focuses on how to build it.

Both tutorials are self-contained but cross-reference each other. You can read them in either order, though starting with the design tutorial may help you understand the "why" before the "how."

File structure

Understanding the file structure helps you navigate and contribute to the docs. Here's what each file does:

HTML pages

  • index.html — The Library tutorial (full implementation code). This is the main technical reference.
  • state-machines.html — The State machine tutorial (design and preplanning). Focuses on concepts and design process.
  • about-docs.html — This page: explains how the docs are created and maintained.

Styling

  • styles.scss — Source stylesheet written in SCSS (Sass). Contains all styling: layout, typography, colors, code blocks, theme (light/dark), responsive design.
  • styles.css — Compiled CSS file (generated from styles.scss). This is what the HTML pages actually load. You should not edit this file directly; edit styles.scss and rebuild.
  • styles.css.map — Source map for debugging SCSS (generated automatically).

JavaScript

  • index.js — Shared front-end functionality used by all HTML pages:
    • Theme toggle (light/dark mode) with localStorage persistence
    • Sidebar toggle for mobile navigation
    • Tutorial stepper (for the Library tutorial's step-by-step guide)
    • Java/Kotlin language toggle for code blocks
    • Table of contents (TOC) active section highlighting on scroll

Configuration

  • package.json — Project metadata and build script. Contains npm run build:css which compiles SCSS to CSS using Sass.
  • README.md — Project overview, links to tutorials, viewing instructions, and CSS build instructions.

Content organization

Each HTML page follows a consistent structure:

  • <header> — Logo, title, navigation links, theme toggle, language toggle
  • <aside class="sidebar"> — Table of contents (TOC) with links to all sections
  • <main class="main"> — All content sections. Each section has id="section-name" and class="section"

Content lives in <section> elements inside <main>. Each section should have a unique id that matches its TOC link (e.g., <section id="introduction"> with TOC link <a href="#introduction">).

Viewing the docs

No build step is required to view the documentation. Simply open any HTML file in a web browser:

  • Drag the HTML file into your browser window
  • Or use File → Open in your browser
  • Or use a simple local server (recommended for development):
    • Python: python3 -m http.server 8000 then visit http://localhost:8000
    • Node.js: npx http-server or npx serve
    • VS Code: Use the "Live Server" extension

All assets (CSS, JavaScript, fonts, Prism syntax highlighting) are either local files or loaded from CDNs, so an internet connection is helpful but not strictly required for offline viewing (except for Google Fonts and CDN-hosted libraries).

Editing content

To add or modify content in the documentation:

Adding a new section

  1. Open the relevant HTML file (index.html or state-machines.html)
  2. Find the <main class="main"> element
  3. Add a new <section id="your-section-name" class="section"> element
  4. Add a heading: <h2>Your Section Title</h2>
  5. Add your content (paragraphs, lists, code blocks, etc.)
  6. Update the table of contents (TOC) in the <aside class="sidebar">:
    • Find the <ul class="toc-list">
    • Add a new list item: <li><a href="#your-section-name">Your Section Title</a></li>
    • Place it in the order you want it to appear

Modifying an existing section

Simply edit the content inside the relevant <section> element. The TOC link will automatically work if the id matches.

Adding content to both tutorials

If you want to add a section that appears in both tutorials (e.g., a shared glossary entry or concept explanation), you'll need to:

  1. Add the section to index.html
  2. Add the same section to state-machines.html
  3. Update the TOC in both files
  4. Keep the content synchronized (or cross-reference if one is more detailed)

For content that's specific to one tutorial (e.g., implementation details in the Library tutorial, design process in the State machine tutorial), only add it to the relevant file.

Code and language toggle

The docs support showing code in both Java and Kotlin. Users can toggle between languages using the buttons in the header. Here's how to add code blocks:

Single-language code block

If you only want to show one language, use a standard <pre><code> block:

<pre><code class="language-java">
public class Example {
    // Java code here
}
</code></pre>

Dual-language code block (with toggle)

To show both Java and Kotlin with a toggle, wrap both code blocks in a <div class="code-demo" data-lang-toggle>:

<div class="code-demo" data-lang-toggle>
  <pre data-lang="java"><code class="language-java">
public class Example {
    // Java code here
}
</code></pre>
  <pre data-lang="kotlin" class="hidden"><code class="language-kotlin">
class Example {
    // Kotlin code here
}
</code></pre>
</div>

Key points:

  • The wrapper <div> must have class="code-demo" and data-lang-toggle
  • Each <pre> must have data-lang="java" or data-lang="kotlin"
  • The Kotlin block should have class="hidden" initially (Java is shown by default)
  • Use Prism language classes: class="language-java" or class="language-kotlin"

The index.js script handles showing/hiding blocks based on the user's language preference (stored in localStorage). Prism syntax highlighting is applied automatically when blocks become visible.

Building CSS

If you edit styles.scss, you need to compile it to CSS before your changes will appear in the browser.

Using npm (recommended)

If you have Node.js installed:

  1. Install dependencies (one time): npm install
  2. Build CSS: npm run build:css

The build script runs sass styles.scss styles.css using the Sass compiler.

Using npx (one-off)

If you don't want to install dependencies locally:

npx sass styles.scss styles.css

When to rebuild

  • After editing styles.scss — Always rebuild to see your changes
  • After editing HTML content — No rebuild needed; just refresh the browser
  • After editing index.js — No rebuild needed; just refresh the browser

The CSS file (styles.css) is generated automatically and should not be edited manually. If you need to make styling changes, edit styles.scss and rebuild.

Diagrams

The State machine tutorial uses Mermaid for UML-style state diagrams. Mermaid is loaded from a CDN and initialized at the bottom of state-machines.html.

Adding a Mermaid diagram

To add a state diagram:

  1. Create a <figure class="uml-figure"> element
  2. Inside it, add a <div class="mermaid state-diagram"> with the Mermaid syntax
  3. Add a <figcaption> to describe the diagram

Example:

<figure class="uml-figure">
  <div class="mermaid state-diagram">stateDiagram-v2
[*] --> IDLE
IDLE --> SHOOT : "after 4s"
SHOOT --> LEAVE : "on complete"
LEAVE --> END : "path done"
END --> [*]</div>
  <figcaption>Example state machine: simple autonomous.</figcaption>
</figure>

Mermaid syntax for state diagrams:

  • [*] — Start/end state (filled circle)
  • --> — Transition arrow
  • : — Label on transition (e.g., IDLE --> SHOOT : "after 4s")
  • State names are written directly (e.g., IDLE, SHOOT)

The Mermaid theme is configured in the script at the bottom of state-machines.html to match the docs' color scheme (purple accent colors).

Note: Only state-machines.html loads Mermaid. If you want to add diagrams to index.html, you'll need to add the Mermaid script and initialization there as well.

Consistency across pages

Both tutorial pages share the same structure and styling. When making changes, keep these in mind:

Header navigation

The header nav links appear in both index.html and state-machines.html. If you add a new page (like this about-docs.html page), update the nav in all HTML files to include a link to it. The active page should have class="is-active" on its nav link.

Sidebar TOC

Each page has its own table of contents in the sidebar. When adding a new section, update the TOC in that page's HTML file. The TOC should match the order of sections in <main>.

Scripts and styles

All pages load:

  • styles.css — Shared styles
  • index.js — Shared JavaScript (theme toggle, sidebar, language toggle, TOC highlighting)
  • Prism (from CDN) — Syntax highlighting for code blocks

If you add new functionality to index.js, it will work on all pages that load it. If you add page-specific scripts (like Mermaid), only add them to the relevant page.

Adding a new tutorial page

If you want to create a completely new tutorial page:

  1. Create a new HTML file (e.g., advanced-topics.html)
  2. Copy the header structure from an existing page
  3. Update the header nav in all HTML files to include a link to the new page
  4. Add your content sections
  5. Create a sidebar TOC for the new page
  6. Load the same CSS and JS files

This ensures consistency in navigation and user experience across all pages.