docs: release v0.6.1 docs portal content and changelog

Beowolve · Beowolve · commit f07a5a8552a2 · 2026-02-28T21:35:54.000+01:00
- move all unreleased documentation updates into CHANGELOG v0.6.1

- add user guide, first-layout tutorial, and examples pages to Docusaurus

- refresh release-status and convert reference URLs to clickable links

- sync STATUS/DONE/ROADMAP with documentation progress
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,6 +8,13 @@ The changelog is grouped by release tags (`vX.Y.Z`) and includes an `Unreleased`
 
 No changes yet.
 
+## v0.6.1 - 2026-02-28
+
+### Documentation
+- ✅ Expanded Docusaurus content baseline with dedicated User Guide, First Layout tutorial, and Examples pages.
+- ✅ Updated docs navigation and entry pages (`intro`, `getting-started`, sidebar) to surface the new onboarding flow.
+- ✅ Refreshed docs link hygiene (clickable references instead of URL code formatting where applicable) and updated release-status content to reflect current `v0.6.x` progress.
+
 ## v0.6.0 - 2026-02-28
 
 ### CI and Documentation
diff --git a/DONE.md b/DONE.md
@@ -139,6 +139,8 @@ SnapFX has been fully implemented with core functionality and is production-read
 - ✅ Added a Docusaurus documentation portal baseline and integrated generated JavaDoc under `/api` so `https://snapfx.org/` now serves guides/overview while keeping API reference at `https://snapfx.org/api/`.
 - ✅ Documented the release policy decision to defer multi-version docs/API publication until after `1.0.0`, keeping pre-`1.0.0` documentation delivery latest-only for lower maintenance overhead.
 - ✅ Backfilled missing release sections in `CHANGELOG.md` for `v0.5.0` and `v0.6.0`, and reset `Unreleased` to post-tag changes only.
+- ✅ Expanded Docusaurus content baseline with a practical User Guide, First Layout tutorial, and Examples catalog, plus sidebar/entry-page cross-linking for faster onboarding.
+- ✅ Completed docs link/status hygiene pass: release-readiness page updated to current `v0.6.x` progression and URL references across docs pages are now rendered as clickable links.
 
 ### Resources
 - ✅ `snapfx.css` - Native Modena theme styling
diff --git a/ROADMAP.md b/ROADMAP.md
@@ -362,11 +362,12 @@ This roadmap keeps a high-level progress view plus planned/proposed work; detail
 - 📋 **Roadmap structure cleanup**: Keep each subsection as one block (`Priority` + open/planned items) and move detailed completed history to [CHANGELOG.md](CHANGELOG.md) / [DONE.md](DONE.md)
 - ✅ **API documentation**: `snapfx-core` JavaDoc completion baseline is now warning-free via `./gradlew :snapfx-core:javadoc --rerun-tasks`, collaboration rules require immediate full JavaDoc updates for new/changed public API, and API docs are now published at `https://snapfx.org/api/`.
 - ✅ **JavaDoc discoverability baseline**: Exported API packages now include `package-info.java` overviews, and key API classes now include usage snippets to improve first-time navigation on hosted docs.
-- 📋 **User guide**: Comprehensive usage guide
-- 📋 **Tutorial series**: Step-by-step tutorials
-- 📋 **Example projects**: Real-world examples
+- ✅ **User guide baseline**: Docusaurus now includes a practical SnapFX user guide covering core concepts, setup flow, docking/floating/sidebars, persistence, and theme usage.
+- ✅ **Tutorial baseline**: Docusaurus now includes a "First Layout" step-by-step tutorial from root setup through save/load.
+- ✅ **Examples baseline**: Docusaurus now includes reusable code examples for common integration patterns (IDE layout, tab grouping, floating, lock mode, shortcuts, themes, save/load).
 - ✅ **GitHub Pages site**: Docusaurus-based documentation portal is now live at `https://snapfx.org/` (guides, architecture, release status) with JavaDoc integrated under `/api`.
 - ✅ **Changelog release hygiene baseline**: `CHANGELOG.md` now keeps explicit sections per release tag (including backfilled `v0.5.0` and `v0.6.0`), and `Unreleased` is reserved for post-tag work.
+- ✅ **Docs link + status hygiene pass**: docs pages now use clickable links for references (including API links), and release-readiness status content is aligned to the current `v0.6.x` state.
 - 📋 **Docs versioning (post-`1.0.0`)**: Start Docusaurus multi-version docs and versioned API JavaDoc paths only after the first stable release to keep pre-`1.0.0` maintenance overhead low.
 - 📋 **Video tutorials**: Screen recordings
 - 📋 **Doc consistency guardrails**: Keep markdown consistency tests aligned with documentation scope rules while avoiding brittle content-specific assertions (focus on encoding/format guardrails)
diff --git a/STATUS.md b/STATUS.md
@@ -23,6 +23,8 @@
 ✅ **Docs Portal Baseline (`0.6.x`)**: GitHub Pages workflow now builds and publishes the Docusaurus documentation portal at `https://snapfx.org/`, bundles generated `:snapfx-core:javadoc` under `/api`, and writes a `CNAME` for `snapfx.org` (`.github/workflows/docs-pages.yml`).
 ✅ **JavaDoc Usability Pass**: Exported API packages now include `package-info.java` overviews, and key entry classes (`SnapFX`, `DockGraph`, `DockLayoutSerializer`, `DockFloatingWindow`) now include concise usage snippets in JavaDoc.
 ✅ **Changelog Tag Backfill**: `CHANGELOG.md` now contains explicit `v0.5.0` and `v0.6.0` sections, and `Unreleased` is reset to post-tag changes only.
+✅ **Docs Content Baseline**: Docusaurus now includes first structured content slices beyond overview pages (User Guide, First Layout tutorial, and Examples catalog) with sidebar navigation wiring.
+✅ **Docs Link/Status Refresh**: Documentation pages now expose references as clickable links (including API references), and release-status content reflects current `v0.6.x` progress.
 
 ## Documentation Scope
 
@@ -233,6 +235,7 @@
 - ✅ Sidebar overlay/pin rendering state split is documented in ADR [docs/adr/0003-sidebar-overlay-and-pin-rendering-state-split.md](docs/adr/0003-sidebar-overlay-and-pin-rendering-state-split.md)
 - ✅ Sidebar panel width state/runtime-clamping behavior is documented in ADR [docs/adr/0004-sidebar-panel-width-state-and-runtime-clamping.md](docs/adr/0004-sidebar-panel-width-state-and-runtime-clamping.md)
 - ✅ Sidebar visibility mode and framework sidebar-menu gating behavior are documented in ADR [docs/adr/0005-sidebar-visibility-mode-and-framework-menu-gating.md](docs/adr/0005-sidebar-visibility-mode-and-framework-menu-gating.md)
+- ✅ Docusaurus content baseline pages are now available at `https://snapfx.org/`: User Guide, First Layout tutorial, and Examples.
 
 ## Issues
 
diff --git a/website/docs/api-reference.md b/website/docs/api-reference.md
@@ -2,7 +2,7 @@
 
 SnapFX API documentation is generated from JavaDoc and published at:
 
-- `https://snapfx.org/api/`
+- [SnapFX API JavaDoc](https://snapfx.org/api/)
 
 ## Main Entry Points
 
diff --git a/website/docs/architecture.md b/website/docs/architecture.md
@@ -13,4 +13,4 @@ Detailed architecture documentation remains in the repository:
 
 For API-level details, use:
 
-- `https://snapfx.org/api/`
+- [API JavaDoc](https://snapfx.org/api/)
diff --git a/website/docs/examples.md b/website/docs/examples.md
@@ -0,0 +1,66 @@
+# Examples
+
+This page collects practical SnapFX usage patterns.
+
+## IDE Layout (Editor + Console + Project)
+
+```java
+DockNode project = new DockNode("project", new TreeView<>(), "Project");
+DockNode editor = new DockNode("editor", new TextArea(), "Editor");
+DockNode console = new DockNode("console", new TextArea(), "Console");
+
+snapFX.getDockGraph().setRoot(editor);
+snapFX.getDockGraph().dock(project, editor, DockPosition.LEFT);
+snapFX.getDockGraph().dock(console, editor, DockPosition.BOTTOM);
+```
+
+## Tab Grouping
+
+```java
+DockNode tasks = new DockNode("tasks", new ListView<>(), "Tasks");
+snapFX.getDockGraph().dock(tasks, console, DockPosition.CENTER);
+```
+
+## Float and Reattach
+
+```java
+DockFloatingWindow floating = snapFX.floatNode(console);
+// ... user works in floating window ...
+snapFX.attachFloatingWindow(floating);
+```
+
+## Layout Locking
+
+```java
+snapFX.setLocked(true);
+// user cannot rearrange or close layout elements while locked
+```
+
+## Shortcut Override
+
+```java
+snapFX.setShortcut(
+    DockShortcutAction.CLOSE_ACTIVE_NODE,
+    new KeyCodeCombination(KeyCode.Q, KeyCombination.SHORTCUT_DOWN)
+);
+```
+
+## Theme Switch
+
+```java
+String dark = SnapFX.getAvailableThemeStylesheets().get("Dark");
+snapFX.setThemeStylesheet(dark);
+```
+
+## Save and Load
+
+```java
+String state = snapFX.saveLayout();
+snapFX.loadLayout(state);
+```
+
+## API Deep Dive
+
+Use JavaDoc for full API details and class-level examples:
+
+- [SnapFX API JavaDoc](https://snapfx.org/api/)
diff --git a/website/docs/getting-started.md b/website/docs/getting-started.md
@@ -30,5 +30,7 @@ Until Maven Central publication is live, use source checkout or GitHub Release d
 
 ## Next
 
-- Read the architecture overview in this docs portal.
-- Use JavaDoc at `/api` for full public API details.
+- Continue with the [User Guide](/user-guide).
+- Follow [Tutorial: First Layout](/tutorial-first-layout) for a complete start-to-finish flow.
+- Browse [Examples](/examples) for reusable snippets.
+- Use [API JavaDoc](https://snapfx.org/api/) for full public API details.
diff --git a/website/docs/intro.md b/website/docs/intro.md
@@ -9,18 +9,21 @@ SnapFX is a lightweight JavaFX docking framework for desktop applications that n
 Use this documentation portal for guides and architecture context.
 Use the generated JavaDoc for detailed API reference.
 
-- Documentation home: `https://snapfx.org/`
-- API JavaDoc: `https://snapfx.org/api/`
-- Source repository: `https://github.com/Beowolve/SnapFX`
+- [Documentation Home](https://snapfx.org/)
+- [API JavaDoc](https://snapfx.org/api/)
+- [Source Repository](https://github.com/Beowolve/SnapFX)
 
 ## What You Can Read Here
 
 - Getting started and setup guidance
+- A practical user guide with core workflows
+- A step-by-step first-layout tutorial
+- Reusable integration examples
 - Architecture overview and design references
 - Release/readiness status references for maintainers
 
 ## API Reference
 
 The full public API JavaDoc is published under:
 
-- `https://snapfx.org/api/`
+- [SnapFX API JavaDoc](https://snapfx.org/api/)
diff --git a/website/docs/release-status.md b/website/docs/release-status.md
@@ -4,12 +4,17 @@ SnapFX follows a release-ready development track before the first stable `1.0.0`
 
 ## Current Position
 
-- `0.5.x`: JavaDoc completeness baseline completed
-- `0.6.x`: Public docs + domain baseline completed
-- `0.7.x`: Packaging hardening in progress
-- `0.8.x`: Publishing readiness planned
-- `0.9.x`: Release rehearsal planned
-- `1.0.0`: Stable cut after readiness gates are green
+- `v0.5.0` released: JavaDoc completeness baseline delivered.
+- `v0.6.0` released: Docusaurus docs portal + hosted API docs baseline delivered.
+- `v0.6.1` scope (in progress): content expansion for user guide/tutorial/examples.
+- `0.7.x`: packaging hardening (cross-platform validation, checksums, smoke workflow polish).
+- `0.8.x`: publishing readiness (Maven Central staging/signing/release flow).
+- `0.9.x`: release rehearsal and API freeze.
+- `1.0.0`: stable cut after all release-readiness gates are green.
+
+## Latest Stable Release
+
+- [v0.6.0 on GitHub Releases](https://github.com/Beowolve/SnapFX/releases/tag/v0.6.0)
 
 ## Canonical Tracking
 
diff --git a/website/docs/tutorial-first-layout.md b/website/docs/tutorial-first-layout.md
@@ -0,0 +1,73 @@
+# Tutorial: First Layout
+
+This tutorial builds a simple IDE-style SnapFX layout in small steps.
+
+## Step 1: Create SnapFX and Root Node
+
+```java
+SnapFX snapFX = new SnapFX();
+
+DockNode editor = new DockNode(
+    "editor.main",
+    new TextArea("Start typing..."),
+    "Editor"
+);
+snapFX.getDockGraph().setRoot(editor);
+```
+
+## Step 2: Add Console and Project Tree
+
+```java
+DockNode console = new DockNode(
+    "console.main",
+    new TextArea("Build output"),
+    "Console"
+);
+
+DockNode project = new DockNode(
+    "project.tree",
+    new TreeView<>(),
+    "Project"
+);
+
+snapFX.getDockGraph().dock(console, editor, DockPosition.BOTTOM);
+snapFX.getDockGraph().dock(project, editor, DockPosition.LEFT);
+```
+
+## Step 3: Build Scene and Initialize
+
+```java
+Scene scene = new Scene(snapFX.buildLayout(), 1200, 760);
+stage.setScene(scene);
+snapFX.initialize(stage);
+stage.setTitle("SnapFX Tutorial");
+stage.show();
+```
+
+## Step 4: Add Persistence Factory
+
+```java
+snapFX.setNodeFactory(nodeId -> switch (nodeId) {
+    case "editor.main" -> new DockNode(nodeId, new TextArea(), "Editor");
+    case "console.main" -> new DockNode(nodeId, new TextArea(), "Console");
+    case "project.tree" -> new DockNode(nodeId, new TreeView<>(), "Project");
+    default -> null;
+});
+```
+
+## Step 5: Save and Restore Layout
+
+```java
+String json = snapFX.saveLayout();
+Files.writeString(Path.of("layout.json"), json);
+
+String loaded = Files.readString(Path.of("layout.json"));
+snapFX.loadLayout(loaded);
+```
+
+## What To Try Next
+
+- Float and reattach a dock node, then review related options in the [User Guide](/user-guide).
+- Test lock mode behavior and persistence with real layout changes.
+- Configure shortcuts and sidebars, then compare with [Examples](/examples).
+- Switch theme at runtime and check API-level details in [API JavaDoc](https://snapfx.org/api/).
diff --git a/website/docs/user-guide.md b/website/docs/user-guide.md
@@ -0,0 +1,97 @@
+# User Guide
+
+This guide covers the main runtime features of SnapFX and the recommended usage flow.
+
+## Core Concepts
+
+- `SnapFX`: main facade API for setup, behavior toggles, and persistence.
+- `DockGraph`: model tree that represents layout structure.
+- `DockNode`: wrapper around each dockable JavaFX `Node` with ID/title/icon metadata.
+
+## Typical Setup Flow
+
+1. Create `SnapFX`.
+2. Create dock nodes (or use facade helpers).
+3. Build and show layout.
+4. Initialize SnapFX with the primary stage.
+
+```java
+SnapFX snapFX = new SnapFX();
+snapFX.dock(new TextArea("Editor"), "Editor");
+snapFX.dock(new TextArea("Console"), "Console");
+
+Scene scene = new Scene(snapFX.buildLayout(), 1100, 700);
+stage.setScene(scene);
+snapFX.initialize(stage);
+stage.show();
+```
+
+## Docking and Layout Composition
+
+- Use `dock(...)` to place new nodes relative to existing nodes.
+- Use `DockPosition.LEFT/RIGHT/TOP/BOTTOM/CENTER` for split/tab targets.
+- Use stable IDs for nodes when you need cross-session restore.
+
+```java
+DockNode editor = new DockNode("editor.main", new TextArea(), "Editor");
+DockNode console = new DockNode("console.main", new TextArea(), "Console");
+snapFX.getDockGraph().setRoot(editor);
+snapFX.getDockGraph().dock(console, editor, DockPosition.BOTTOM);
+```
+
+## Floating Windows
+
+- Float any node with `floatNode(...)`.
+- Attach floating windows back with `attachFloatingWindow(...)`.
+- Configure always-on-top behavior and snap settings through API.
+
+```java
+DockFloatingWindow floating = snapFX.floatNode(editor);
+snapFX.attachFloatingWindow(floating);
+```
+
+## Sidebars
+
+SnapFX supports left/right sidebar workflows for pinned tool windows:
+
+- move nodes to sidebars
+- restore from sidebars
+- pinned-open vs collapsed panel behavior
+- optional sidebar visibility modes (`ALWAYS`, `AUTO`, `NEVER`)
+
+## Persistence
+
+For robust save/load across restarts:
+
+- assign stable node IDs
+- register a node factory that can recreate nodes from IDs
+
+```java
+snapFX.setNodeFactory(nodeId -> switch (nodeId) {
+    case "editor.main" -> new DockNode(nodeId, new TextArea(), "Editor");
+    case "console.main" -> new DockNode(nodeId, new TextArea(), "Console");
+    default -> null;
+});
+
+String json = snapFX.saveLayout();
+snapFX.loadLayout(json);
+```
+
+## Themes
+
+- default theme is auto-applied on `initialize(...)`
+- runtime switching is supported via `setThemeStylesheet(...)`
+- built-in named themes are exposed by the API
+
+## Recommended Workflow
+
+1. Model your primary use cases in MainDemo-like layout patterns.
+2. Add persistence and verify load behavior with factory-backed IDs.
+3. Enable lock mode for final user-facing safety where needed.
+4. Add regression tests for model-level behavior changes.
+
+## Related References
+
+- [Examples](/examples)
+- [Tutorial: First Layout](/tutorial-first-layout)
+- [API JavaDoc](https://snapfx.org/api/)
diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js
@@ -98,7 +98,7 @@ const config = {
           ]
         }
       ],
-      copyright: `Copyright © ${new Date().getFullYear()} SnapFX contributors`
+      copyright: `Copyright (c) ${new Date().getFullYear()} SnapFX contributors`
     }
   }
 };
diff --git a/website/sidebars.js b/website/sidebars.js
@@ -5,6 +5,9 @@ const sidebars = {
   docsSidebar: [
     "intro",
     "getting-started",
+    "user-guide",
+    "tutorial-first-layout",
+    "examples",
     "architecture",
     "api-reference",
     "release-status"

Original file line number	Diff line number	Diff line change
`@@ -13,4 +13,4 @@ Detailed architecture documentation remains in the repository:`
`13`	`13`
`14`	`14`	`For API-level details, use:`
`15`	`15`
`16`		-- `https://snapfx.org/api/`
	`16`	`+- [API JavaDoc](https://snapfx.org/api/)`