Docs... Lots of Docs.

Author: coatless

docs/_quarto.yml

@@ -8,31 +8,52 @@ website:
   repo-actions: [edit, issue]
   sidebar:
     logo: "toggle-animated-logo.svg"
-    logo-alt: "A hexagon logo for the toggle Quarto extension."
+    logo-alt: "Toggle extension logo"
     style: "floating"
     search: true
     tools:
       - icon: github
         href: https://github.com/coatless-quarto/toggle/
-    contents: 
-      - text: "Home"
-        file: index.qmd
-      - section: "Examples"
+    contents:
+      - section: "Get Started"
         contents:
-        - text: "Toggle for All Cells"
-          href: qtoggle-all-cells-example.qmd
-        - text: "Toggle Specific Cells"
-          href: qtoggle-specific-cells-example.qmd
-      - section: "Support"
+        - text: "Home"
+          href: index.qmd
+        - text: "Quick Start"
+          href: qtoggle-quick-start.qmd
+      - section: "Features"
         contents:
+        - text: "Hide by Default"
+          href: qtoggle-hidden-default.qmd
+        - text: "Sync Multiple Outputs"
+          href: qtoggle-sync-mode.qmd
+        - text: "Global Control"
+          href: qtoggle-global-toggle.qmd
+        - text: "Remember State"
+          href: qtoggle-persistence.qmd
+        - text: "Custom Labels"
+          href: qtoggle-custom-text.qmd
+      - section: "Demos"
+        contents:
+        - text: "Nested Containers"
+          href: qtoggle-nested-containers.qmd
+        - text: "Data Analysis Demo"
+          href: qtoggle-demo.qmd
+      - section: "Reference"
+        contents:
+        - text: "Custom Styling"
+          href: qtoggle-styling.qmd
         - text: "FAQ"
           href: qtoggle-faq.qmd
-        - text: "Submit an issue"
-          href: https://github.com/coatless-quarto/toggle/issues/new/choose
-      - section: "Extra"
-        contents:
-        - qtoggle-release-notes.qmd
+        - text: "Release Notes"
+          href: qtoggle-release-notes.qmd
+      - text: "---"
+      - text: "Report Issue"
+        href: https://github.com/coatless-quarto/toggle/issues/new/choose
 
-format: 
+format:
   html:
     toc: true
+    theme:
+      light: flatly
+      dark: darkly

docs/index.qmd

@@ -1,89 +1,85 @@
 ---
-title: "Home"
-format: 
+title: "Toggle"
+subtitle: "Let readers control output visibility in Quarto documents"
+format:
   html:
-    toc: false
+    toc: true
 ---
 
-The `toggle` extension allows you to toggle between showing code with output or just code by itself in Quarto HTML documents by adding a convenient toggle button that appears when hovering over code blocks, similar to the copy button.
+Ever wished readers could hide verbose output while keeping the code visible?
+The `toggle` extension adds a button to your code blocks that shows or hides
+the output on demand.
 
-## Installation
-
-To install the `toggle` extension, follow these steps:
-
-1. Open your terminal.
+Think of it as the opposite of Quarto's
+[`code-fold`](https://quarto.org/docs/output-formats/html-code.html#folding-code).
+Instead of hiding code and showing output, toggle hides output and shows code.
 
-2. Execute the following command:
+## Installation
 
 ```bash
 quarto add coatless-quarto/toggle
 ```
 
-This command will download and install the extension under the `_extensions` subdirectory of your Quarto project. If you are using version control, ensure that you include this directory in your repository.
-
-## Usage
+## Quick Start
 
-At the top of your Quarto document, include the `filters` key with `toggle` specified in the YAML header:
+Add the filter and enable toggle for all cells:
 
 ```yaml
----
-title: "My Document"
-format: html
+extensions:
+  toggle:
+    output-toggle: true
 filters:
   - toggle
----
 ```
 
-This will allow the toggle extension to be applied to your document.
-
-### Cell-Level Configuration
+Hover over any code block to see the toggle button appear. Click to hide the
+output; click again to show it.
 
-To enable toggle functionality for a specific code cell, add the `toggle: true` attribute:
-
-````md
-```{{python}}
-#| toggle: true
-print("Hello, Python world!")
-```
-````
-
-You can also set whether the output is shown or hidden by default using the `output-hidden` attribute:
+To enable toggle for specific cells only, omit `output-toggle` and add
+`#| toggle: true` to individual cells:
 
 ````md
 ```{{r}}
 #| toggle: true
-#| output-hidden: true
-print("Hello, R world!")
+summary(mtcars)
 ```
 ````
 
-This will hide the output by default, and the user can click the toggle button to show it.
+## Options
 
-### Document-Level Configuration
+Set these under `extensions.toggle` or per-cell with `#|` comments:
 
-You can enable toggle functionality for all code cells in your document by adding the following to your YAML header:
+| Option | Default | Purpose |
+|--------|---------|---------|
+| `output-toggle` | `false` | Add toggle buttons to all cells |
+| `output-hidden` | `false` | Start with outputs collapsed |
+| `output-sync` | `false` | Sync all outputs in a cell together |
+| `global-toggle` | `false` | Floating button to toggle everything |
+| `persist` | `false` | Remember state across page reloads |
+| `button-text` | `"Output"` | Label shown on the button |
 
-```yaml
----
-title: "My Document"
-format: html
-toggle:
-  output-toggle: true    # Enable toggle buttons for all cells
-  output-hidden: false   # Show outputs initially (default)
-filters:
-  - toggle
----
-```
+## Compatibility
 
-#### Priority of Settings
+Works with HTML-based Quarto formats: documents, websites, books, and Revealjs
+presentations.
 
-- Cell-level settings override document-level settings
-- If no cell-level setting is provided, document-level settings apply
-- If neither is provided, toggle is not enabled for that cell
+Toggle complements Quarto's
+[`code-fold`](https://quarto.org/docs/output-formats/html-code.html#folding-code).
+Use both together:
 
-## Help
+```yaml
+format:
+  html:
+    code-fold: true
+extensions:
+  toggle:
+    output-toggle: true
+```
 
-To report a bug, please [add an issue](https://github.com/coatless-quarto/toggle/issues/new) to the repository's [bug tracker](https://github.com/coatless-quarto/toggle/issues).
+PDF, Word, and other non-HTML formats are unaffected.
 
-Want to contribute a feature? Please open an issue ticket to discuss the feature before sending a pull request. 
+## Getting Help
 
+- [FAQ](qtoggle-faq.qmd) — Common questions
+- [GitHub Issues](https://github.com/coatless-quarto/toggle/issues) — Bug reports
+- [Discussions](https://github.com/coatless-quarto/toggle/discussions) — Questions