Skip to content

tutorial-platform-analysis.md

Latest commit

 

History

History
314 lines (187 loc) · 23.6 KB

tutorial-platform-analysis.md

File metadata and controls

314 lines (187 loc) · 23.6 KB

Interactive Tutorial Platform Analysis

Date: March 2026
Context: FRC Java Programming Tutorial — evaluating platforms that support custom Markdown content, user progress tracking, and embedded knowledge check questions.

Key Requirements

  1. Markdown-based content authoring — existing content is in .md format
  2. Knowledge check / quiz questions — embedded assessments within tutorial pages
  3. User progress tracking — learners can save and resume their progress
  4. Extensibility — ability to add custom features over time
  5. Static / self-hostable — GitHub Pages or similar, no backend required

Important Ecosystem Note (March 2026)

Material for MkDocs entered maintenance mode in November 2025. Version 9.7.0 is the last feature release. The maintainer has launched a successor product called Zensical (MIT licensed, MkDocs-YAML compatible) and will provide only critical security/bug fixes for Material through approximately November 2026. MkDocs 1.x core is also unmaintained. A community-driven MkDocs 2.0 rewrite is planned but is explicitly incompatible with Material for MkDocs and its plugin ecosystem.

This is a significant risk factor for long-term platform planning, though it does not affect short-term functionality.

Platform Summaries

1. MkDocs + Material Theme (current stack)

Python-based static site generator using YAML configuration. Material for MkDocs adds a polished responsive theme, admonitions, tabbed content, code annotations, Mermaid diagrams, and extensive PyMdown Extensions.

Markdown Support: Excellent — PyMdown Extensions provide tasklists, superfences (Mermaid), tabbed content, inline highlights, snippets (file inclusion), admonitions, and more.

Quiz Support:

  • mkdocs-quiz (Apache 2.0, v1.6.2, March 2026 — actively maintained): Full-featured quiz plugin using GFM checkbox syntax. Supports single-choice, multiple-choice, and fill-in-the-blank. Provides per-answer feedback, answer explanations, answer shuffling, and confetti on completion.
  • A second plugin mkdocs_quiz (by bdallard) offers a simpler alternative with score display and progress bar.

Progress Tracking:

  • mkdocs-quiz stores all answers and results in browser localStorage, persisting across sessions. Includes a progress sidebar showing answered/correct counts.
  • mkdocs-material-mark-as-read (MIT): lets users manually mark pages as read, stored in localStorage.
  • Material's built-in navigation.tracking updates the URL fragment as users scroll.
  • No built-in cross-page "X of Y modules completed" dashboard without custom JavaScript.

LMS Export: mkdocs-quiz supports QTI export (Canvas, Blackboard, Moodle) — unique among all platforms reviewed.

Hosting: Any static host (GitHub Pages, Netlify, Cloudflare Pages, Read the Docs, S3). Zero vendor lock-in.

Customization: High — YAML-driven config, custom CSS via extra_css, custom JS via extra_javascript, HTML overrides via overrides/ directory.

Ecosystem: Large Python documentation community with hundreds of plugins. However, the maintenance-mode announcement is a significant long-term risk.

Verdict: Strongest out-of-the-box quiz and progress story of all platforms reviewed. mkdocs-quiz installs with a single pip install, activates with three lines in mkdocs.yml, and delivers working quizzes immediately — with no framework migration required.

2. Docusaurus

Meta's React-based static site generator (MIT, 57,000+ GitHub stars). Version 3.9 released late 2025. Production-grade, used by React, Jest, Webpack, and hundreds of major OSS projects.

Markdown Support: Excellent — uses MDX (Markdown + JSX), allowing any React component to be embedded directly in .mdx files. Supports admonitions, live code editors, Mermaid, math, tabs, and more via remark/rehype plugins.

Quiz Support:

  • No official quiz plugin. The Docusaurus team declined to build one, citing MDX's ability to embed custom React components.
  • @sp-days-framework/docusaurus-plugin-interactive-tasks: provides interactive checklist-style tasks with hints, solutions, completion tracking via localStorage, sidebar badges, and cross-tab sync. Not a traditional quiz but a solid approximation.
  • Custom React quiz components can be authored and imported in .mdx files — state management (localStorage or backend) is handled by the component author.

Progress Tracking:

  • No built-in cross-page progress tracking.
  • The interactive-tasks plugin provides per-task completion state with sidebar badges.
  • Custom solutions using React useEffect/localStorage or a backend (Supabase, Firebase) are straightforward.

Hosting: Any static host (GitHub Pages, Netlify, Vercel, Cloudflare Pages, S3).

Customization: Very high for React developers. Component swizzling overrides any built-in element. The trade-off is a Node.js/React build stack more complex for Python-oriented teams.

Ecosystem: Largest documentation SSG community. 75+ community plugins. Actively developed with no maintenance concerns.

Verdict: High ceiling, low floor. Powerful MDX + React combination enables any quiz or progress UI imaginable, but requires non-trivial development effort compared to a ready-made plugin. Best choice if the project has React expertise or needs quiz UI beyond multiple-choice (e.g., embedded code exercises, interactive diagrams).

3. VitePress

Vite + Vue 3 powered static site generator (MIT) by the Vue.js team. Used by Vue.js, Vite, Vitest, and Rollup official documentation.

Markdown Support: Very good — CommonMark + GFM, custom containers (tip/warning/danger/details), math, Mermaid, Vue components used directly in .md files (no .mdx conversion needed).

Quiz Support: No dedicated quiz plugin exists. Vue Single-File Components (SFCs) can be written and embedded in Markdown, making custom quiz components feasible for Vue developers.

Progress Tracking: No built-in tracking. Custom Vue <ProgressTracker> component with localStorage is achievable.

Hosting: Any static host (GitHub Pages, Netlify, Vercel, Cloudflare Pages).

Customization: High for Vue developers. Theme customization via CSS variables and component overrides. Configuration in TypeScript.

Ecosystem: Mid-sized but growing, concentrated around Vue. Smaller than Docusaurus, larger than Nextra.

Verdict: Similar capability to Docusaurus via Vue components, but no ready-made quiz or progress plugin. Requires Vue expertise. Less suitable for a Python/MkDocs team without a framework migration.

4. Astro + Starlight

Astro is a multi-framework static site builder (MIT) known for its "islands architecture" — zero JS shipped by default, components hydrated on demand. Starlight is Astro's official documentation theme. Astro 5.x (2025) introduced 5x faster Markdown builds and Live Content Collections.

Markdown Support: Excellent — full MDX with Zod schema validation on frontmatter, Shiki syntax highlighting, math, Mermaid, remark/rehype plugins. Starlight adds its own content model.

Quiz Support: No dedicated Starlight quiz plugin exists. Astro's MDX supports React, Vue, Svelte, Solid, Preact, and Alpine components in the same file — the broadest multi-framework interoperability of any platform reviewed.

Progress Tracking: No built-in learner progress tracking in Starlight. Astro's islands architecture supports client:load interactive components with localStorage access.

Hosting: Netlify, Vercel, Cloudflare Pages, GitHub Pages, AWS, self-hosted. Astro's adapter system also supports SSR (server-side rendering), enabling server-backed progress tracking without a separate API — unique among static SSGs.

Customization: Very high. Starlight allows component overrides, custom CSS, and plugin hooks.

Ecosystem: Large and rapidly growing. Starlight has 40+ community plugins but lacks educational tooling specifically.

Verdict: High ceiling, currently zero floor on quiz/progress plugins for Starlight. The SSR adapter option is the most powerful path to authenticated, server-persisted progress tracking among all platforms reviewed. Strong long-term candidate for a rebuild if custom components are acceptable.

5. GitBook

Commercial SaaS documentation platform (AI-native, cloud-only as of 2025). The legacy open-source GitBook (v2/v3) and its plugin ecosystem are abandoned.

Markdown Support: Good — web editor with GitHub sync. Lacks fine-grained Markdown extension control.

Quiz Support: Legacy open-source GitBook had two quiz plugins (plugin-quizzes, plugin-quiz) supporting radio/checkbox questions. Modern GitBook SaaS has no quiz feature. 2025 product updates focused on AI features (Lens AI search, auto-localization) — not interactive assessments.

Progress Tracking: None. Analytics integrations (Google Analytics, Slack) track page views, not learner completion.

Hosting: GitBook.com only. No self-hosted option. Custom domains on paid plans.

Pricing (2026): Site plan required to publish. Plus: ~$10/user/month. Pro (AI): substantially higher.

Customization: Low — limited to GitBook's built-in block system. No custom CSS/JS without workarounds.

Verdict: Not recommended. No quiz support in the modern platform, SaaS-only hosting, pricing concerns for a volunteer/FRC team project, and no self-hosted path.

6. Docsify

JavaScript runtime Markdown renderer (MIT). No build step — Markdown is fetched and rendered client-side. Extremely simple setup.

Markdown Support: Good — CommonMark + GFM. Custom markdown-it plugins supported.

Quiz Support: No quiz plugin in the 120+ plugin ecosystem. docsify-interactive-checkboxes adds persistent checkbox tasks but not true quiz functionality.

Progress Tracking: docsify-progress shows a reading scroll-position bar (cosmetic, not persisted between visits). No cross-page completion tracking exists.

Hosting: Any static host. Zero build process = simplest possible deployment. GitHub Pages trivially supported.

Customization: Moderate — vanilla JS plugin API. No component system.

Key Weakness: Runtime rendering means search engines see an empty page until JavaScript executes — significant SEO limitations. Performance degrades on large documentation sets.

Verdict: Lowest capability for quiz and progress tracking. The no-build simplicity is appealing but insufficient for a structured tutorial platform requiring assessments.

7. Nextra

Next.js-based documentation framework (MIT, v4 with App Router support). Used by some major documentation sites.

Markdown Support: Excellent via MDX. Full React component embedding, math, syntax highlighting, custom remark/rehype plugins.

Quiz Support: No dedicated plugin. Custom React quiz components can be authored in MDX files.

Progress Tracking: No built-in tracking. Nextra 4 on App Router can use Next.js API routes for server-side progress, but this requires a backend host (not static GitHub Pages).

Hosting: Vercel (first-class), Netlify, Cloudflare Pages (static export). GitHub Pages requires output: 'export' mode, which disables dynamic features.

Customization: High for Next.js/React developers. Less documentation-community tooling than Docusaurus.

Verdict: Similar capability to Docusaurus but with a smaller ecosystem, Vercel-biased hosting, and no plugin directory. Not recommended unless the team is already in the Next.js ecosystem. Fumadocs is frequently cited as a better-maintained Next.js documentation alternative in 2026.

8. mdBook

Rust-based static site generator (Apache 2.0 / MIT) maintained by the Rust language team. Used for official Rust documentation.

Markdown Support: CommonMark + some GFM extensions. Custom preprocessors (Rust or any subprocess). MathJax and Mermaid via preprocessors.

Quiz Support:

  • mdbook-quiz (Apache 2.0 + MIT, v0.4.0, 148 GitHub stars): dedicated quiz preprocessor with questions authored in TOML files. Question types: ShortAnswer, MultipleChoice, and Tracing (predict Rust code output — Rust-specific). Used by Will Crichton's Rust learning materials at Brown University.
  • mdbook-exercises (December 2025): interactive exercise blocks with hints, solutions, Rust Playground integration, difficulty levels, time estimates.
  • cache-answers = true stores user answers in localStorage.

Progress Tracking: mdbook-quiz with cache-answers persists quiz answers. No cross-book progress dashboard.

Hosting: Any static host. GitHub Pages is first-class with documented CI workflows.

Customization: Moderate — CSS overrides, custom JS, custom HTML. No component system.

Ecosystem: Focused Rust community. Well-suited for Rust content; weaker for general programming education.

Verdict: Excellent quiz infrastructure if you accept the Rust toolchain dependency and Rust-centric question types. mdbook-quiz is the most production-proven quiz plugin outside mkdocs-quiz. However, the Tracing question type is Rust-specific and migration from MkDocs is substantial.

9. LiaScript (Purpose-Built)

Open-source browser-based Markdown interpreter (MIT) extended with interactive learning primitives. Developed at TU Bergakademie Freiberg for Open Educational Resources. No server or build step required.

Markdown Support: Extended CommonMark dialect with LiaScript-specific extensions: text-to-speech, animated presentations, executable code blocks, and native quiz syntax.

Quiz Support (Built-In): Multiple choice, single choice, matrix questions, gap text (fill-in-the-blank), text input, dropdown — all authored directly in Markdown, no plugins needed. Answers stored in localStorage with native progress tracking.

Progress Tracking: Built-in. LiaScript is a Progressive Web App (PWA) and stores course progress locally. Works offline after first load.

LMS Export: SCORM 1.2 and SCORM 2004 export via LiaScript-Exporter CLI. Also exports to IMS, PDF, standalone web project, and Android APK. Most LMS-compatible platform reviewed — supports Moodle, ILIAS, OpenOlat, Canvas, Blackboard.

Hosting: Content can be served from GitHub, GitLab, Nextcloud, Dropbox, IPFS, and more. The LiaScript interpreter loads from a CDN and processes a Markdown URL — content and renderer are completely decoupled.

Customization: Moderate. The UX is presentation/course-oriented (slides-style navigation), less documentation-site-like. Deep customization requires modifying the interpreter.

Ecosystem: Smaller, concentrated in academic/OER communities. Growing international adoption for low-bandwidth educational deployments.

Verdict: Strongest built-in quiz and progress story of any platform reviewed — without plugins. SCORM export is uniquely valuable for LMS integration with school-based FRC programs. The trade-off is a more course/presentation-oriented UX and a smaller developer community.

Feature Comparison Matrix

Feature MkDocs + Material Docusaurus VitePress Astro/Starlight GitBook Docsify Nextra mdBook LiaScript
Markdown quality Excellent Excellent (MDX) Very Good Excellent (MDX) Good Good Excellent (MDX) Good Extended MD
Quiz plugin exists Yes Partial (tasks) No No Legacy only No No Yes Built-in
Quiz question types MC, multi, fill-blank Tasks/checklists Custom Vue Custom component Legacy: radio/CB Custom JS only Custom React SC, SA, Tracing MC, SC, matrix, gap, text, dropdown
Answer persistence localStorage localStorage (tasks) Manual Manual None None Manual localStorage localStorage (PWA)
Cross-page progress Mark-as-read plugin Tasks plugin (sidebar) Manual Manual None None Manual Manual Built-in
LMS export QTI (quiz plugin) None None None None None None None SCORM 1.2/2004
Self-hostable Yes Yes Yes Yes No Yes Yes (static) Yes Yes
Component system Jinja2 + vanilla JS React (MDX) Vue (inline) Multi-framework None Vanilla JS React (MDX) Vanilla JS None (built-in)
Extensibility High (Python plugins) Very High (React) High (Vue) Very High (multi-FW) Low (SaaS) Moderate High (React) Moderate (Rust) Low (fixed)
Ecosystem size Large (in transition) Very Large Medium Large & growing Large (locked) Medium Small Small (Rust) Small (academic)
Maintenance status Maintenance mode Active (Meta) Active (Vue team) Very active Active (SaaS) Slow Active Active (Rust team) Active
License MIT MIT MIT MIT Proprietary SaaS MIT MIT Apache 2.0/MIT MIT
Setup complexity Low (pip) Medium (Node/React) Medium (Node/Vue) Medium (Node) None (SaaS) Very Low Medium (Node/React) Medium (Rust) Very Low (CDN)

Recommendations

Recommendation 1 — Minimal effort, maximum immediate capability

Stay on MkDocs + Material and add mkdocs-quiz and mkdocs-material-mark-as-read.

pip install mkdocs-quiz mkdocs-material-mark-as-read

Add to mkdocs.yml:

plugins:
  - search
  - quiz
  - mark-as-read

This delivers:

  • Multiple question types (single choice, multiple choice, fill-in-the-blank) using familiar checkbox Markdown syntax
  • localStorage answer persistence with a progress sidebar, out of the box
  • QTI export for future LMS integration
  • Page-level completion tracking ("mark as read")

No framework migration. No new toolchain. Existing content unchanged. Working quizzes within an hour of setup.

The Material maintenance-mode concern is real but not urgent — existing functionality is stable. Monitor Zensical (the MIT-licensed successor by the same maintainer) as the natural long-term migration target with minimal content changes.

Recommendation 2 — Migration path with maximum extensibility

Migrate to Docusaurus if React expertise exists and the project needs quiz UI beyond multiple-choice (e.g., embedded code exercises, interactive robot simulators, code-grading sandboxes).

MDX allows any React component in any page. The @sp-days-framework/docusaurus-plugin-interactive-tasks provides structured task completion with sidebar badges immediately. Custom quiz components can be built incrementally. Docusaurus has no maintenance concerns and the largest ecosystem.

Migration cost: several days — mkdocs.yml nav → docusaurus.config.js, PyMdown admonition syntax → Docusaurus admonition syntax, custom overrides rebuild.

Recommendation 3 — LMS integration requirement

Evaluate LiaScript alongside the existing MkDocs reference site if FRC tutorial content needs to integrate with school LMS platforms (Moodle, Canvas) for grading or credit.

LiaScript Markdown files can live in the same GitHub repository. SCORM export is a one-command CLI operation. The course content (Markdown) is shared; only the rendering layer differs between the MkDocs documentation site and the LiaScript course export.

Long-term watch: Zensical

Zensical (MIT, by the Material for MkDocs team) is the spiritual successor to Material for MkDocs. It reads existing mkdocs.yml files and opens its module/plugin system to third-party developers in early 2026. Once the ecosystem matures — especially if mkdocs-quiz authors publish a compatible version — it is the natural migration target from the current stack with minimal content changes.

Sources