docs: comprehensive documentation review and updates (#1809)

Signed-off-by: Pedro Lamas <pedrolamas@gmail.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
(cherry picked from commit 773dbba)

Author: pedrolamas

.github/workflows/docs.yml

@@ -18,7 +18,7 @@ jobs:
           python-version: '3.x'
 
       - name: Install Zensical
-        run: pip install "zensical==0.0.29"
+        run: pip install "zensical==0.0.30"
 
       - name: Build docs
         run: zensical build --clean

CLAUDE.md

@@ -90,7 +90,7 @@ npm run circular-check # Check for circular dependencies
 
 ### File Organization
 
-```
+```text
 src/
 ├── api/                # HTTP (axios) and WebSocket (custom JSON-RPC) clients
 ├── components/
@@ -134,7 +134,7 @@ src/
 - Setup in `src/components/widgets/filesystem/setupMonaco.ts`
 - TextMate grammars (onigasm WASM) for `gcode`, `klipper-config`, `log` languages
 - Custom CodeLens providers (links to Klipper docs from config sections)
-- Document symbol + folding range providers for klipper-config and gcode
+- Document symbol + folding range providers for `klipper-config` and `gcode`
 - Worker setup in `setupMonaco.features.ts` (editor, JSON, CSS workers)
 
 ## Integration Points
@@ -227,7 +227,7 @@ src/
 
 ### Documentation Structure
 
-```
+```text
 docs/
 ├── docs/                  # Markdown content
 │   ├── index.md           # Homepage
@@ -240,6 +240,9 @@ docs/
 │   │   ├── thermals.md    # Chart, presets, sensors
 │   │   ├── cameras.md
 │   │   ├── console.md
+│   │   ├── file-editor.md  # Monaco editor features, syntax, CodeLens, folding
+│   │   ├── keyboard-shortcuts.md  # Global, editor, console keyboard shortcuts
+│   │   ├── file-manager.md  # File browser, upload, search, previews, drag-and-drop
 │   │   ├── macros.md
 │   │   ├── multi-material.md  # Multiple extruders + Spoolman
 │   │   ├── multiple-printers.md
@@ -265,11 +268,16 @@ docs/
 
 - Frontmatter: `title` (required), `icon` (top-level pages only, Lucide icons)
 - Images: `/assets/images/` path, stored in `docs/docs/assets/images/`
-- Code blocks: `ini` for Klipper/Moonraker config, `bash` for shell commands, `json` for JSON
+- Code blocks must always have a language tag: `ini` for Klipper/Moonraker config, `bash` for shell commands, `json` for JSON, `text` when no language applies
+- Zensical uses Python-Markdown which requires 4-space indentation per nesting level for all block-level elements nested in lists (sub-lists, paragraphs, code blocks, blockquotes) — no tabs
+- Tables must use aligned pipe style (columns padded to equal width)
 - Links: use `{.md-button}` attribute for standalone action links
 - Keys: use `++key++` syntax (pymdownx.keys extension) instead of `<kbd>`
 - Terminology: G-code (not gcode/Gcode), Wi-Fi (not WiFi), GitHub (not Github), Node.js (not NodeJS), SD card (not SDCard), em dash (—) not hyphen (-) for parenthetical dashes
-- Glossary terms (AFC, API, CORS, JWT, MCU, MMU, MPC, PID, etc.) get automatic tooltips
+- Klipper macro names: format as inline code (e.g., `PAUSE`, `SET_PAUSE_AT_LAYER`, `_CLIENT_VARIABLE`)
+- Klipper/Moonraker section names and config variable names: format as inline code (e.g., `[virtual_sdcard]`, `enable_object_processing`) — exception: leave unformatted when used as markdown headings
+- Glossary terms (AFC, API, CNC, CORS, JWT, MCU, MMU, MPC, PID, etc.) get automatic tooltips via `docs/includes/glossary.md`
+- When introducing acronyms in docs, check if they exist in the glossary — if not, assess whether they should be added (domain-specific or non-obvious acronyms: yes; universally known ones like USB, HTTP, CPU: no)
 - **Before committing docs changes**, always run:
   - `markdownlint --config docs/.markdownlint.json docs/docs/` — must be clean
   - `codespell docs/docs/` — must be clean (install via `pip install codespell`)

docs/.markdownlint.json

@@ -1,4 +1,7 @@
 {
+  "MD007": { "indent": 4 },
+  "MD010": true,
   "MD013": false,
-  "MD025": false
+  "MD025": false,
+  "MD060": { "style": "aligned" }
 }

docs/docs/assets/images/automated-updates.png

@@ -58,13 +58,31 @@ Fluidd-config provides enhanced versions of the standard macros with additional
 capabilities:
 
 - Configurable park positions (round beds, square beds, or custom coordinates)
-- Enhanced PAUSE macro with optional X, Y, and Z_MIN parameters
+- Separate park positions for `PAUSE` and `CANCEL_PRINT`
+- Enhanced `PAUSE` macro with optional X, Y, and Z_MIN parameters
 - Pause at next layer or at a specific layer number
-- Temperature management during pause/resume cycles
-- Filament runout sensor integration
-- Configurable idle timeout behavior
+- Temperature management during pause/resume cycles (save/restore extruder
+  temperature with idle timeout integration)
+- Configurable retraction and unretraction with firmware retraction support
+- Filament runout sensor integration (blocks `RESUME` if no filament detected)
+- Configurable idle timeout behavior during `PAUSE` state
+- User-injectable custom macros in `PAUSE`/`RESUME`/`CANCEL_PRINT` flows
+- Safer toolhead movement commands via `_CLIENT_LINEAR_MOVE`
 - Support for printers without extruders (e.g. CNC machines)
 
+### Fluidd UI Integration
+
+When fluidd-config is installed, Fluidd automatically detects its macros and
+enables additional UI features:
+
+- **Pause at layer** — the `SET_PAUSE_NEXT_LAYER` and `SET_PAUSE_AT_LAYER`
+  macros enable a pause-at-layer dropdown in the print controls, allowing you
+  to pause or trigger an `M600` filament change at a specific layer
+- **Toolhead park button** — the `PARK_TOOLHEAD` macro adds a park button to
+  the toolhead card
+- **Filament load/unload buttons** — the `LOAD_FILAMENT` and `UNLOAD_FILAMENT`
+  macros add dedicated buttons to the toolhead card
+
 ### Customization
 
 You can customize the behavior by overriding the `_CLIENT_VARIABLE` macro in
@@ -83,9 +101,9 @@ For more detailed instructions, please refer to the [Klipper documentation](http
 
 ### [virtual_sdcard]
 
-Fluidd requires your printer to be set up with `virtual_sdcard`. This allows
-file uploads to work correctly. If you get a G-code path not found error in
-Fluidd, this is generally the first place to look.
+Fluidd requires `virtual_sdcard` to upload, browse, and print G-code files.
+Without this, Fluidd cannot manage files on your printer. If you get a
+G-code path not found error, this is generally the first place to look.
 
 ```ini title="printer.cfg"
 [virtual_sdcard]
@@ -94,15 +112,18 @@ path: ~/printer_data/gcodes
 
 ### [display_status]
 
-Required to properly support display updates in Fluidd, with no other lines required.
+Required for Fluidd to show print progress percentages and M117 display
+messages. No additional configuration is needed.
 
 ```ini title="printer.cfg"
 [display_status]
 ```
 
 ### [pause_resume]
 
-Enables Pause / Resume functionality within klipper. This is a single block, with no other lines required.
+Enables the Pause, Resume, and Cancel buttons in Fluidd's print controls.
+Without this, Fluidd cannot pause or cancel a running print. No additional
+configuration is needed.
 
 ```ini title="printer.cfg"
 [pause_resume]
@@ -222,8 +243,9 @@ This is especially useful for temperature store data, as it
 directly affects how much time data is stored on the X axes of
 the thermals graph.
 
-Temperature store size is in seconds, while the G-code store size is defined
-in an entry count.
+Both values are entry counts. Temperature entries are stored once per second by
+default, so a value of 600 corresponds to approximately 10 minutes of history.
+The G-code store size is also defined as an entry count.
 
 ```ini title="moonraker.conf"
 [data_store]
@@ -287,11 +309,24 @@ subscriptions:
   fluidd
 ```
 
+### [analysis]
+
+Enables G-code print time estimation using Moonraker's built-in estimator.
+When enabled, Fluidd shows a "Perform Time Analysis" action in the file
+browser — available for single files via context menu or in bulk. Results are
+stored in file metadata and update the estimated print time displayed in the
+file list.
+
+### [job_queue]
+
+Enables the job queue feature. When enabled, Fluidd shows a job queue card on
+the dashboard, a queue tab on the Jobs page, and "Add to queue" actions in the
+file browser context menu and bulk actions toolbar.
+
 ### [update_manager]
 
 Automated updates can be configured by ensuring the following is in your
-`moonraker.conf`. Moonraker automatically refreshes update status approximately
-every two hours. Update requests are blocked while a print is in progress.
+`moonraker.conf`. Update requests are blocked while a print is in progress.
 
 ```ini title="moonraker.conf"
 [update_manager]
@@ -342,6 +377,10 @@ trusted_clients:
 
 [octoprint_compat]
 
+[analysis]
+
+[job_queue]
+
 [update_manager]
 
 [announcements]

docs/docs/configuration.md

@@ -10,14 +10,17 @@ and control which components are visible.
 
 ## Application Layout
 
-Fluidd allows you to adjust your dashboard layout to your liking. Use the
-hamburger menu and click the `adjust layout` option.
+Fluidd's dashboard uses a multi-column layout. On desktop, cards are arranged
+across left and right columns. On mobile, they collapse into a single column.
 
-Use the drag handles to move cards to / from the left and right columns. You
-can also easily disable cards if you have no use for them.
+To adjust the layout, open the side menu and click **Adjust Layout**:
 
-Once you're done, click the exit layout mode button. You can reset back to
-the default layout by clicking reset layout.
+- **Drag** cards between columns or reorder them within a column using the
+  drag handles.
+- **Enable or disable** individual cards using the checkboxes — disabled
+  cards are hidden from the dashboard.
+- Click **Exit Layout** when you are done, or **Reset Layout** to restore
+  the default arrangement.
 
 ![screenshot](/assets/images/layout.png)
 
@@ -28,16 +31,19 @@ the default layout by clicking reset layout.
 Fluidd lets you choose a community preset, apply a color of your
 choosing — along with either a dark or light theme.
 
-Community presets are a way for Fluidd to support 3D printing communities. If
-you'd like to see your logo supported here, let us know!
+Community presets are themed around popular 3D printing brands and
+communities. If you'd like to see your logo supported here, let us know!
+
+You can also set any custom primary color and independently toggle between
+dark and light mode without using a preset.
 
 ![screenshot](/assets/images/theme.png)
 
-### Community Themes
+### Custom Themes
 
-Fluidd offers a way for custom stylesheets and background images to be included.
-All custom theming is configured through a `.fluidd-theme` folder within your
-configuration files.
+Fluidd supports custom stylesheets and background images. All custom theming
+is configured through a `.fluidd-theme` folder within your configuration
+files.
 
 #### Custom Background
 
@@ -50,12 +56,17 @@ Currently, the following file extensions are supported:
 - `.png`
 - `.gif`
 
+#### Custom Logo
+
+To replace the Fluidd logo in the sidebar, upload a `logo.svg` or `logo.png`
+file to the `.fluidd-theme` folder in your configuration directory. The logo
+will appear in the application bar after reloading Fluidd.
+
 #### Custom Styling
 
-Fluidd offers a [curated list of community themes](https://github.com/fluidd-core/themes).
-To use a community theme, simply upload the themes `custom.css` file to the
-`.fluidd-theme` directory.
-After a reload of Fluidd the changes should become visible.
+To apply custom CSS, create a `custom.css` file and upload it to the
+`.fluidd-theme` directory. After reloading Fluidd the changes should become
+visible.
 
 ## Hiding Components
 

docs/docs/customize.md

@@ -8,6 +8,12 @@ icon: lucide/wrench
 Fluidd is built using VueJS, and the Vuetify Framework to provide a cohesive,
 easy to implement UI.
 
+## Contributing
+
+Contributions are welcome! Please review the
+[CONTRIBUTING.md](https://github.com/fluidd-core/fluidd/blob/develop/CONTRIBUTING.md)
+file before submitting a pull request.
+
 ## Dev Container in Visual Studio Code
 
 Fluidd includes a Dev Container configuration to easily open with Visual Studio Code

docs/docs/development.md

@@ -9,6 +9,40 @@ Answers to common questions about Fluidd, Klipper, and Moonraker.
 
 ## Setup & Configuration
 
+### How do I use app.fluidd.xyz?
+
+[app.fluidd.xyz](https://app.fluidd.xyz) is a hosted version of Fluidd that
+runs entirely in your browser. It communicates directly with your printer on
+your local network — no data leaves your network.
+
+To use it, add `*://app.fluidd.xyz` to the `cors_domains` section of your
+`moonraker.conf` and restart Moonraker. See
+[Getting Started](/getting-started#fluiddxyz) for details.
+
+### Fluidd cannot connect to my printer
+
+Try these steps in order:
+
+1. Verify Moonraker is running by opening
+   `http://<your-printer>/server/info` in your browser. If this does not
+   load, Moonraker is not running or not reachable.
+2. Check the `cors_domains` section in your `moonraker.conf` — the host you
+   are connecting from must be listed. See the
+   [configuration example](/configuration#example-configuration).
+3. Check the `trusted_clients` section — your IP range must be included.
+4. If you are connecting from a different network or through a VPN, verify
+   there are no firewall rules blocking the connection.
+
+### My printer shows as disconnected
+
+This usually means Klipper is not running or has encountered a configuration
+error. Open the Fluidd console — if there is an error message, it will
+describe what went wrong. Common fixes:
+
+- Check your `printer.cfg` for syntax errors.
+- Try running `FIRMWARE_RESTART` from the console.
+- Restart the Klipper service from the [System page](/features/system).
+
 ### Klipper updated and now my printer has an error
 
 Klipper likely has configuration changes. See the
@@ -31,6 +65,22 @@ Updates can sometimes fail and cause this error. Fluidd provides a recovery
 option — try that first. If it fails, reach out on
 [Discord](https://discord.gg/GZ3D5tqfcF).
 
+### How do I back up my configuration?
+
+Three options:
+
+- **Fluidd settings backup** — go to Settings and use the backup and restore
+  options to save or load your Fluidd UI settings (layout, theme, presets,
+  macros, etc.).
+- **Moonraker database backup** — go to the
+  [System page](/features/system), find the database section, and click
+  Create Backup to save a backup on the host. Use Restore to select and
+  restore from an existing backup.
+- **Config files** — your Klipper and Moonraker configuration files are
+  stored in `~/printer_data/config`. You can copy this directory manually
+  via SSH or use the [File Manager](/features/file-manager) to download
+  individual files.
+
 ## Cameras
 
 ### How do I turn on my camera?
@@ -54,6 +104,31 @@ A few suggestions:
   resolution in your streamer configuration (e.g.
   [Crowsnest](https://crowsnest.mainsail.xyz/)). Wired ethernet also helps.
 
+## Printing
+
+### Does Fluidd show a total layer count?
+
+Yes. Fluidd displays the current layer and total layer count during a print,
+provided your slicer includes layer information in the G-code file.
+
+### How do I set up Exclude Object?
+
+Exclude Object lets you cancel individual objects mid-print. Three things are
+required:
+
+1. Enable **Label Objects** in your slicer.
+2. Add an `[exclude_object]` section to your `printer.cfg`.
+3. Set `enable_object_processing: True` in the `[file_manager]` section of
+   your `moonraker.conf`.
+
+Files must be uploaded after enabling these settings. See
+[Printing — Exclude Object](/features/printing#exclude-object) for details.
+
+### How do I upload files from my slicer?
+
+See [Slicer Uploads](/features/slicer-uploads) for setup instructions
+covering OrcaSlicer, PrusaSlicer, SuperSlicer, and Cura.
+
 ## System
 
 ### The host reboot / shutdown commands don't work
@@ -73,9 +148,17 @@ following to `/etc/rc.local` and rebooting:
 iwconfig wlan0 power off
 ```
 
-## Printing
+## Customization
 
-### Does Fluidd show a total layer count?
+### How do I change the dashboard layout?
 
-Yes. Fluidd displays the current layer and total layer count during a print,
-provided your slicer includes layer information in the G-code file.
+Open the side menu and click **Adjust Layout**. You can drag cards between
+columns, reorder them, or disable cards you don't need. Click the exit button
+when done, or use **Reset Layout** to restore the defaults. See
+[Customize](/customize#application-layout) for more details.
+
+### How do I use a custom theme?
+
+Create a `.fluidd-theme` folder in your configuration directory and upload a
+`custom.css` file into it. Fluidd also supports custom backgrounds and logos.
+See [Customize — Custom Themes](/customize#custom-themes) for details.