Improve documentation coverage

docs/README.md

@@ -27,13 +27,15 @@ guides under *Getting started*.
 - [Complex layout tutorials](dock-complex-layouts.md) – Multi-window and plug-in walkthroughs.
 - [Styling and theming](dock-styling.md) – Customize the appearance of Dock controls.
 - [Control recycling](dock-control-recycling.md) – Reuse visuals when dockables return.
+- [Proportional StackPanel](dock-proportional-stackpanel.md) – Layout panel with adjustable proportions.
 - [Advanced guide](dock-advanced.md) – Custom factories and runtime features.
 
 ## Reference
 
 - [Reference guide](dock-reference.md) – Overview of the core APIs.
 - [Glossary](dock-glossary.md) – Definitions of common Dock terms.
 - [Dockable property settings](dock-dockable-properties.md) – Configure per item behaviour.
+- [Markup extensions](dock-markup-extensions.md) – Load and reference XAML fragments.
 
 ## Troubleshooting
 

docs/dock-markup-extensions.md

@@ -0,0 +1,30 @@
+# Dock Markup Extensions
+
+Dock ships with two simple markup extensions that complement Avalonia's XAML loader. They are distributed in the `Dock.MarkupExtension` package and can be used independently from the docking system.
+
+## `LoadExtension`
+
+`LoadExtension` loads a XAML fragment from a URI at runtime and returns the resulting object instance. This is handy when you want to keep small pieces of XAML in separate files without creating data templates.
+
+```xaml
+<TextBlock Text="{markup:Load 'resm:Views/StatusView.axaml?assembly=MyApp'}"/>
+```
+
+The URI is resolved relative to the current `IUriContext`. Any element type can be loaded. When used as a binding the created object becomes the property value.
+
+## `ReferenceExtension`
+
+`ReferenceExtension` returns an element by name from the current `INameScope`. It mirrors the behaviour of WPF's `x:Reference` markup extension.
+
+```xaml
+<StackPanel>
+  <Button x:Name="OkButton" Content="OK"/>
+  <TextBlock Text="{markup:Reference OkButton.Content}"/>
+</StackPanel>
+```
+
+The extension searches the nearest name scope for an element called `OkButton` and returns it. This can be used to bind properties between two elements declared in the same scope.
+
+Both extensions reside in the `Avalonia.MarkupExtension` namespace and can be imported in XAML using `xmlns:markup="clr-namespace:Avalonia.MarkupExtension"`.
+
+For an overview of all guides see the [documentation index](README.md).

docs/dock-proportional-stackpanel.md

@@ -0,0 +1,31 @@
+# Proportional StackPanel
+
+`ProportionalStackPanel` is an Avalonia `Panel` included with Dock that sizes its children based on a `Proportion` value. The panel works horizontally or vertically and exposes attached properties to control layout behaviour.
+
+## Key features
+
+- **Orientation** – determines whether children are arranged horizontally or vertically.
+- **ProportionProperty** – attached property that specifies the size ratio for each child. Values are normalized so that all proportions add up to `1`.
+- **IsCollapsedProperty** – attached property that temporarily collapses a child without removing it from the layout.
+- **ProportionalStackPanelSplitter** – interactive splitter used to adjust proportions at runtime. Insert between two children.
+
+## Basic usage
+
+```xaml
+<psp:ProportionalStackPanel Orientation="Horizontal"
+                           xmlns:psp="clr-namespace:Dock.Controls.ProportionalStackPanel">
+  <Border psp:ProportionalStackPanel.Proportion="0.3" Background="Red"/>
+  <psp:ProportionalStackPanelSplitter />
+  <Border psp:ProportionalStackPanel.Proportion="0.7" Background="Green"/>
+</psp:ProportionalStackPanel>
+```
+
+The example creates a horizontal panel with two regions separated by a splitter. Dragging the splitter resizes the regions while keeping their proportions within the available space.
+
+`IsCollapsed` can be toggled to hide a region and redistribute its proportion among the remaining children.
+
+## Notes
+
+The control is used internally by Dock to implement `ProportionalDock` but can also be used in regular Avalonia views. See the unit tests under `tests/Dock.Avalonia.UnitTests` for additional examples.
+
+For an overview of all guides see the [documentation index](README.md).