Skip to content

📄 Guided — Page Architecture

Last updated: 24 April 2026
Status: Live — cert landing + vendor pages redesigned
Applies to: Dynamic cert pages ([slug]), vendor pages ([vendor]), and static cert pages

Overview

Guided has 4 page types:

Page Route File Count
Homepage /guided/ src/pages/index.astro 1
Vendor page /guided/{vendor}/ src/pages/[vendor]/index.astro 13
Cert landing /guided/{code}/ src/pages/[slug]/index.astro ~90 (dynamic)
Static cert /guided/az-900/ etc. src/pages/{code}/index.astro ~35 (Microsoft only)
Practice exam /guided/{code}/practice/ src/pages/[cert]/practice.astro ~126
Dashboard /guided/dashboard/ src/pages/dashboard/index.astro 1

Route priority

Astro static pages beat dynamic routes. So src/pages/az-900/index.astro serves /guided/az-900/ instead of [slug]/index.astro. The ~35 Microsoft certs with static pages still use the old PathLayout and haven't been migrated to the new design yet.

Migration needed: Static cert pages should eventually be deleted so all certs use the dynamic [slug] route with the new design.

Cert Landing Page ([slug]/index.astro)

Purpose

The conversion page. Users land here from Google → must be convinced to try the free study guide or practice exam. Every section earns its place.

Data Sources

Data Source Loaded at
Cert metadata src/content/certs/{code}.toml Build time (Astro content collection)
Domain info src/data/questions/{code}-domain-*.json Build time (import.meta.glob)
Vendor info src/data/vendors.ts Build time (import)
User progress localStorage (guided-history, guided-sr, guided-perf) Client-side JS

Section Layout

# Section Content Conditional
1 JSON-LD FAQPage (6–8 dynamic questions) Always
2 Hero Breadcrumb, badges (code + vendor + level), h1, tagline, stat pills, feature pills Always
3 Progress Readiness ring (SVG), last score, due flashcards, continue CTA Only if localStorage has data
4 Mode Cards Study (green) / Exam (blue) / Flashcards (amber) — 3-column grid Only if status === 'live'
5 Domains Domain name + weight % + question count + per-domain perf bars Only if domain JSON files exist
6 About the Exam Official exam details: duration, questions, passing score, cost, provider, validity, prerequisites, question types Only if exam_duration or exam_passing_score exists
7 What's Included 6-card trust grid: explanations, adaptive, exam sim, tracking, SR, gamification Always
8 Pricing 3 cards: $19 this cert / $59 vendor pass / $149 all-access Always
9 Bottom CTA Glass card with "Start Practicing" + "More {Vendor} Certs" Always
10 FAQ Accordion matching JSON-LD, first open Always
11 Freshness Content updated date + exam version If dates exist

Hero Badges

[AZ-104] [Microsoft (blue)] [🔵 Intermediate]
  • Cert code: accent variant badge
  • Vendor: pill with vendor.accent background + border
  • Level: mapped from 12 raw levels → 4 display levels with emoji + colour

Feature Pills (below hero)

✅ Adaptive Learning | 🧠 Spaced Repetition | ⏱️ Exam Simulation | 📝 Detailed Explanations

Each pill has a semantic colour (success/info/accent/achievement).

Progress Section (client-side)

Hidden by default (class="hidden"). JavaScript runs on load:

  1. Constructs practice path: basePath + slug + '/practice'
  2. Reads localStorage.getItem('guided-history') keyed by that path
  3. Calculates readiness using same formula as StudyDashboard.tsx (weighted avg of last 3 full attempts)
  4. Animates SVG readiness ring via stroke-dashoffset
  5. Reads guided-sr for due flashcard count
  6. Reads most recent domainScores from history for per-domain performance bars

Domain Breakdown (build-time)

Domains are extracted from question JSON filenames at build time:

/src/data/questions/{code}-domain-{N}.json → meta.domainName + meta.weight + questions.length

Important: The cert slug is parsed from the filename (not meta.cert), because meta.cert is often just the short exam code (e.g. "SY0-701") while the slug is the full code (e.g. "comptia-sy0-701").

Each domain links to /{code}/practice/?domain={N} for targeted practice.

About the Exam Section

Built from TOML fields:

# Official exam details (all optional)
exam_url = "https://..."
exam_duration = 90
exam_questions_real = "Up to 90"
exam_passing_score = "750 / 900"
exam_cost = "$404 USD"
exam_provider = "Pearson VUE"
exam_validity = "3 years"
exam_prerequisites = "CompTIA Network+ recommended"
exam_question_types = ["Multiple choice", "Performance-based (PBQ)"]

If none of these fields exist, the section is hidden. The cost comparison callout ("Exam costs $404 — our practice is $19") only shows when exam_cost exists.

FAQ (JSON-LD + visible)

6–8 questions dynamically generated from cert data:

  1. What is the passing score? (if exam_passing_score)
  2. How long is the exam? (if exam_duration)
  3. How much does the exam cost? (if exam_cost)
  4. How many questions? (if exam_questions_real)
  5. Prerequisites? (if exam_prerequisites)
  6. How long is certification valid? (if exam_validity)
  7. Is the practice exam worth it? (always)
  8. How do I prepare? (always)

Vendor Page ([vendor]/index.astro)

Purpose

SEO entry point for "{vendor} certification practice exams". Shows all certs for one vendor with progress integration.

Section Layout

# Section Content
1 JSON-LD FAQPage (7 questions) + ItemList (cert carousel)
2 Hero SVG logo, vendor name, tagline, stats (certs/questions/guides/exams), recommended path
3 Cert Grid Grouped by level (🟢 Beginner → 🔵 Intermediate → 🟣 Advanced → ⭐ Specialty)
4 Official Link Link to vendor's cert page
5 Why Prepare 4-card trust grid: total questions, 3 modes, adaptive, 20 free
6 FAQ 7 vendor-specific questions (accordion)
7 Other Vendors Pill links to other vendor pages

Cert Cards with Progress (client-side)

Each card has:

  • data-cert-slug attribute for JS targeting
  • Hidden .readiness-badge — JS shows it with readiness % and colour
  • Hidden .due-indicator — JS shows due flashcard count

Colour coding:

  • Green (≥85%): bg-success text-white
  • Amber (≥70%): bg-achievement text-on-strong
  • Grey (default): bg-surface-raised text-text-muted

ItemList JSON-LD

Lists all certs for the vendor with position, name, description, and URL. Enables Google to show a cert carousel in search results.

How to Add a New Cert

Minimum (practice-only cert)

  1. Create TOML: src/content/certs/{code}.toml

    code = "vendor-exam-code"
vendor = "vendor-slug"
name = "Certification Name"
tagline = "One-line hook"
description = "2-3 sentence description"
category = "cloud"  # cloud|security|networking|ai|data|devops|admin|business
level = "associate"  # fundamentals|associate|expert|specialty|entry|core|...
status = "live"
modules = 0
questions = 200
domains = 5
price_practice = 19
price_bundle = 0

  2. Add exam metadata (run scripts/populate-exam-metadata.cjs or add manually):

    exam_url = "https://..."
exam_duration = 120
exam_questions_real = "65"
exam_passing_score = "720 / 1000"
exam_cost = "$150 USD"
exam_provider = "Pearson VUE"
exam_validity = "3 years"
exam_question_types = ["Multiple choice", "Multiple response"]

  3. Add question JSON files: src/data/questions/{code}-domain-{N}.json

    {
  "meta": {
    "cert": "EXAM-CODE",
    "certName": "Full Name",
    "domain": "domain-1",
    "domainName": "Domain Title",
    "weight": 30
  },
  "questions": [ ... ]
}

  4. Done. No page edits needed. The dynamic route generates the cert landing page, practice page, and adds it to the homepage catalog and vendor page automatically.

Full cert (study guide + practice)

Same as above, plus:

  • Set modules = N in TOML
  • Add MDX module files in src/content/{code}/
  • The cert landing page will automatically show study guide features and "Free Study Guide" messaging

Design System Reference

Token Dark value Usage
--color-base #0B1120 Page background
--color-accent #2DD4BF Teal — primary accent, CTAs
--color-achievement #F59E0B Amber — gamification, flashcards
--color-success #10B981 Green — correct, free, study mode
--color-info #3B82F6 Blue — exam mode, intermediate level
--color-error #EF4444 Red — incorrect, warnings
Component File Notes
Card src/components/ui/Card.astro glass/raised/interactive variants
Badge src/components/ui/Badge.astro accent/success/warning/etc variants
Button src/components/ui/Button.astro primary/secondary/outline/ghost
glass-card src/styles/global.css Glassmorphism with backdrop-blur
hover-lift src/styles/global.css Subtle lift on hover