Development

STRUCTURE.md

@@ -184,6 +184,35 @@ they're after instead of landing on the page and hunting.
   anchor/link it can't resolve; treat a clean build as the actual pass/fail check for this list,
   since hand-checked slugs are easy to get subtly wrong (trailing punctuation, duplicate-heading
   suffixes, etc).
+- **Marking content "advanced" for the Simplify toggle** — the header's "Essentials" / "Advanced"
+  segmented control (both labels always visible, on every page) hides content marked
+  `data-advanced="true"`, at one of two granularities. Each spot that should hide is marked
+  directly, in its own markdown source — there's no derived/shared list, so a new advanced entry
+  needs tagging in every place it should disappear from:
+  - **A homepage keyword-link row** — the bolded keyword plus its row of related links (e.g.
+    `functions.md#decorators` or `collections.md#sets`, in `index.md`) — append
+    `{: data-advanced="true" }` on its own line directly after the row, at the same indentation,
+    with no blank line before it (attr_list attaches it to that paragraph, which
+    `.simplify-active [data-advanced]` then hides).
+  - **The matching heading on the actual content page** — e.g. `functions.md`'s
+    `## Decorators { data-advanced="true" }` — append `{ data-advanced="true" }` directly on the
+    heading line (same attr_list convention as `data-card-link="skip"` above). This hides that
+    heading, everything up to the next heading of the same or higher level, and its
+    integrated-TOC sidebar entry, on that page specifically. Tag the homepage row and the
+    content-page heading independently — `docs/javascripts/essentials_toggle.js` doesn't infer one
+    from the other, by design (simpler and more robust than deriving a map at runtime).
+  - **A whole homepage card** (e.g. the OpenCV card) — append `{: data-advanced="card" }` the
+    same way, right after the card's first paragraph (the icon + title link, e.g.
+    `[__OpenCV__](...)`). `.simplify-active .grid.cards > ul > li:has(> p[data-advanced="card"])`
+    in `extra.css` walks up from that paragraph to hide the whole enclosing `<li>`. This one has
+    no content-page equivalent — it marks a whole linked page, not a section within one, so
+    there's nothing on that page itself to hide.
+  Which value to use, and what counts as advanced/niche vs. core, is a per-editor judgment call
+  — there's no test enforcing it either way. See `docs/javascripts/essentials_toggle.js` for the
+  toggle mechanism. A page can still show a *link* to a hidden section (e.g. `collections.md`'s
+  own cheat-sheet table links to `#tuples` even though the "Tuples" heading is hidden) —
+  following such a link automatically switches back to Complete and reveals the target, so this
+  doesn't need special-casing when adding new advanced content.
 
 ### Admonitions (`??? type "..."`)
 

docs/about.md

@@ -6,11 +6,25 @@ description: Why Python Field Guide exists, who built it, and how to send feedba
 
 <div class="pfg-section" markdown="block">
 
+## What is Python?
+
+Python is a general-purpose language built for code that's easy to read back later, even by someone who didn't write it. There's no compiling: write a `.py` file, run it directly.
+
+It shows up everywhere — web backends, data analysis and machine learning, automating repetitive tasks, scientific computing, quick glue scripts. Several of these are covered on this site's [Libraries](index.md#utilities) pages.
+
+The fundamentals every language shares — variables, conditionals, loops, functions, classes — read closer to plain English in Python, so you spend your effort learning to think like a programmer instead of fighting a stricter syntax. Once those fundamentals are solid, they carry over to whatever language you pick up next.
+
+Python is often the fastest language to write *correct* code in, even though it's not the fastest to *run*, which is why it's such a common first choice for a new project.
+
+</div>
+
+<div class="pfg-section" markdown="block">
+
 ## Why I built this
 
 My name's Luka, I'm a software engineer and Intro Python teacher. 
 
-I built this from scratch — it started as a few quick-reference explanations for students working on their first programs, and evolved into this site. 
+*Python Field Guide* is a free, in-browser reference — most code blocks are editable and runnable directly on the page. It started as a few quick-reference explanations for students working on their first programs, and evolved into this site. 
 
 I couldn't find a site my students would consistently use that had: 
 
@@ -21,6 +35,8 @@ I couldn't find a site my students would consistently use that had:
 - quick intuitive navigation
 - clean, minimal UI
 
+It's built for learners — self-taught, students in an intro course, or anyone who wants one combined reference to work through start to finish, instead of a scattered pile of search results.
+
 I'm hoping this can be a helpful cheatsheet for others to quickly reference syntax and structures. 
 
 </div>

docs/collections.md

@@ -760,7 +760,7 @@ flowchart LR
 
 <div class="pfg-section" markdown="block">
 
-## Tuples
+## Tuples { data-advanced="true" }
 
 A tuple stores multiple items, in order, written in parentheses. They are **immutable** so the items can't be changed once its created. 
 
@@ -1033,7 +1033,7 @@ The **negative index** starts counting down from the end instead, starting at `-
 
 <div class="pfg-section" markdown="block">
 
-## Sets
+## Sets { data-advanced="true" }
 
 A set stores multiple items, in no particular order, inside a single variable — written with curly braces.
 

docs/foundations.md

@@ -18,7 +18,7 @@ description: >-
     - [Print debugging](errors.md#print-debugging)
     - [Isolate the problem](errors.md#isolate-the-problem)
 - **Try building something small.** Once you've read through [Conditionals](conditionals.md) and [Loops](loops.md) you already have enough to write a program. 
-- The homepage FAQ has more on [using AI to help you learn](index.md#faq).
+- The homepage has more on [using AI to help you learn](index.md).
 
 </div>
 
@@ -44,7 +44,7 @@ flowchart LR
     classDef terminal fill:none,stroke-width:2px
     class start,stop terminal
 
-    classDef blackbox fill:#000,color:#fff,stroke:#fff,stroke-width:1px
+    classDef blackbox stroke-width:1px
     class black blackbox
 ```
 
@@ -57,38 +57,19 @@ flowchart LR
 <div class="pfg-diagram-frame" markdown="block">
 
 ```mermaid
-flowchart TB
-
-subgraph top[" "]
-direction LR
-black@{ shape: procs, label: "your program" }
-stop@{ shape: dbl-circ, label: "end ■" }
-start(("start ▶"))
-start --> black --> stop
-end
-
-p1["print(...)"]
-p2["print(...)"]
-p3["print(...)"]
-
-black -.-> p1
-black -.-> p2
-black -.-> p3
-
-style top fill:none,stroke:none
-
-classDef terminal fill:none,stroke-width:2px
-class start,stop terminal
+flowchart LR
+    black@{ shape: procs, label: "your program\nprint(...)\nprint(...)\nprint(...)" }
+    stop@{ shape: dbl-circ, label: "end ■" }
+    start(("start ▶"))
+    start --> black --> stop
 
-classDef blackbox fill:#000,color:#fff,stroke:#fff,stroke-width:1px
-class black blackbox
+    classDef terminal fill:none,stroke-width:2px
+    class start,stop terminal
 
-classDef plain fill:none,stroke:none
-class p1,p2,p3 plain
+    classDef blackbox stroke-width:1px
+    class black blackbox
 ```
 
-<p class="pfg-diagram-caption">FIG: print() checkpoints along a running program</p>
-
 </div>
 
 Code editors have an **output** window at the bottom that shows the print statements as the program runs.
@@ -100,41 +81,13 @@ Code editors have an **output** window at the bottom that shows the print statem
 <div class="pfg-diagram-frame" markdown="block">
 
 ```mermaid
-flowchart TB
-
-subgraph code[" "]
-direction LR
-
-p("print")
-o("(")
-s("data")
-c(")")
-
-p -.- o -.- s -.- c
-
-end
-
-f("the function name `print`")
-pa("opening parenthesis")
-st("the data you want to see: a word, number, variable, etc")
-pc("closing parenthesis")
-
-f --> p
-pa --> o
-st --> s
-pc --> c
-
-classDef plain fill:none,stroke:none
-class f,pa,st,pc plain
+flowchart LR
+p("print") -.- o("(") -.- s("value you want to see") -.- c(")")
 
 classDef punct stroke:none
 class p,o,c punct
-
-style code fill:none,stroke:none
 ```
 
-<p class="pfg-diagram-caption">FIG: the parts of a print() statement</p>
-
 </div>
 
 ```python-ref
@@ -416,47 +369,13 @@ The text inside the parentheses — `"What's your first name? "` — is the **pr
 <div class="pfg-diagram-frame" markdown="block">
 
 ```mermaid
-flowchart TB
-
-subgraph code[" "]
-direction LR
-
-n("name")
-eq("=")
-i("input")
-o("(")
-s("&quot;What's your name? &quot;")
-c(")")
-
-n -.- eq -.- i -.- o -.- s -.- c
-
-end
-
-nl("the variable to save the answer in")
-eql("the assignment operator")
-il("the function name `input`")
-pa("opening parenthesis")
-sl("the prompt: a message shown before waiting")
-pc("closing parenthesis")
-
-nl --> n
-eql --> eq
-il --> i
-pa --> o
-sl --> s
-pc --> c
-
-classDef plain fill:none,stroke:none
-class nl,eql,il,pa,sl,pc plain
+flowchart LR
+n("variable_name") -.- eq("=") -.- i("input") -.- o("(") -.- q1("&quot;") -.- s("Prompt the user for the value you want") -.- q2("&quot;") -.- c(")")
 
 classDef punct stroke:none
-class eq,i,o,c punct
-
-style code fill:none,stroke:none
+class eq,i,o,c,q1,q2 punct
 ```
 
-<p class="pfg-diagram-caption">FIG: the parts of an input() statement</p>
-
 </div>
 
 **Prompt format:**

docs/functions.md

@@ -323,7 +323,7 @@ describe(species="ball", length_ft=5)
 
 <div class="pfg-section" markdown="block">
 
-## Scope
+## Scope { data-advanced="true" }
 
 A variable created inside a function is **local** — it only exists while that function is running, and isn't visible outside it.
 
@@ -394,7 +394,7 @@ def show_species():
 
 <div class="pfg-section" markdown="block">
 
-## Recursion
+## Recursion { data-advanced="true" }
 
 A function can call itself — this is called **recursion**, an alternative to a loop for problems that break down into smaller versions of themselves.
 
@@ -460,7 +460,7 @@ Every recursive function needs two parts:
 
 <div class="pfg-section" markdown="block">
 
-## Decorators
+## Decorators { data-advanced="true" }
 
 **`@decorator`** lets you add behavior to a function without editing the function's own code — write the behavior once, then apply it to as many functions as you want. It's written as `@decorator_name`, placed directly above a `def`, and takes one function in, returning a function out[^callable].
 
@@ -470,7 +470,7 @@ A decorator can run its own code around a function call by returning a different
 
 ```python
 def decorator_name(func):              # func is the function being decorated (here it's "describe()")
-    def wrapper():                     # desfines a new function that runs in place of func from now on
+    def wrapper():                     # defines a new function that runs in place of func from now on
         print("looking up a snake...")
         func()                         # calls the original, still reachable through func
         print("found it")