// Guide for writing and improving documentation for SkiaSharp.Extended. Use this skill when creating, updating, or reviewing documentation pages, writing code examples for docs, generating screenshots for documentation, or improving existing docs.
| name | docs-writer |
| description | Guide for writing and improving documentation for SkiaSharp.Extended. Use this skill when creating, updating, or reviewing documentation pages, writing code examples for docs, generating screenshots for documentation, or improving existing docs. |
This skill provides guidance for writing effective documentation for SkiaSharp.Extended.
[API Reference](xref:SkiaSharp.Extended.SKBlurHash)components-comparison.png)docs/images/extended/<feature>/ or docs/images/ui/controls/<control>/Each documentation page follows this pattern:
# Feature Name
Brief intro - what it is, the problem it solves (1-2 sentences)
[Hero image or comparison - e.g., before/after, original vs processed]
## Quick Start
- Encode/create: one code example
- Decode/use: one code example
## How It Works
- Brief explanation of underlying concepts
- Credit original creators if external technology
- Visual showing key concept if helpful
## Customization
- Key parameters and options with explanations
- Tables for parameters when helpful (reduces need to check API docs)
- Visual comparisons showing effect of different parameter values
## Usage Patterns
- Real-world integration examples (API responses, data models)
- MAUI binding/converter examples where applicable
- Brief XAML usage example
## Learn More
- Link to official site (if external technology like BlurHash, Lottie)
- Link to GitHub/source repository
- Link to origin story or detailed explanations
- Link to API reference using xref
For features based on external technologies (BlurHash, Lottie, etc.):
## Learn More
- [BlurHash.sh](https://blurha.sh/) — Official demo and explanation
- [BlurHash GitHub](https://github.com/woltapp/blurhash) — Original algorithm by Dag Ågren at Wolt
- [How Wolt created BlurHash](https://careers.wolt.com/en/blog/tech/...) — The origin story
- [API Reference](xref:SkiaSharp.Extended.SKBlurHash) — Full method documentation
When parameters need explanation:
| Components | String Length | Best For |
| :--------: | :-----------: | :------- |
| 2x2 | ~12 chars | Simple gradients |
| 4x3 | ~28 chars | Most images (recommended) |
| 6x6 | ~76 chars | Complex images with fine detail |
Generate screenshots using a temporary console app in /tmp/:
mkdir -p /tmp/docs-screenshots
cd /tmp/docs-screenshots
Create a minimal .csproj:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net10.0</TargetFramework>
</PropertyGroup>
<ItemGroup>
<ProjectReference Include="/path/to/source/SkiaSharp.Extended/SkiaSharp.Extended.csproj" />
</ItemGroup>
</Project>
Write Program.cs to generate comparison images, then run:
dotnet run
docs/images/extended/<feature>/using SkiaSharp;
var configs = new[] { (2, 2), (4, 3), (6, 6) };
var cellWidth = 200;
var padding = 10;
using var surface = SKSurface.Create(new SKImageInfo(totalWidth, totalHeight));
var canvas = surface.Canvas;
canvas.Clear(SKColors.White);
// Draw each variant side-by-side with labels
for (int i = 0; i < configs.Length; i++)
{
// Generate image for this config
// Draw to canvas at position
// Add label below
}
using var image = surface.Snapshot();
using var data = image.Encode(SKEncodedImageFormat.Png, 100);
File.WriteAllBytes("comparison.png", data.ToArray());
Discuss approach case-by-case - may require running on actual platforms. Existing GIFs in the repo can be kept.
Always test MAUI code in a real project before including in docs.
mkdir -p /tmp/maui-test
cd /tmp/maui-test
dotnet new maui -n TestApp
cd TestApp
dotnet add package SkiaSharp.Views.Maui.Controls
dotnet add reference /path/to/source/SkiaSharp.Extended/SkiaSharp.Extended.csproj
dotnet build -f net10.0-maccatalyst # or net10.0-android
Use the implicit conversion to SKBitmapImageSource (cross-platform, not Windows-specific):
using SkiaSharp;
using SkiaSharp.Views.Maui.Controls;
SKBitmap bitmap = /* ... */;
ImageSource source = (SKBitmapImageSource)bitmap;
Do NOT use ToWriteableBitmap() - that's Windows-only.
Include configurable properties for flexibility:
using System.Globalization;
using SkiaSharp;
using SkiaSharp.Extended;
using SkiaSharp.Views.Maui.Controls;
public class BlurHashConverter : IValueConverter
{
public int Width { get; set; } = 32;
public int Height { get; set; } = 32;
public object? Convert(object? value, Type targetType, object? parameter, CultureInfo culture)
{
if (value is string hash && !string.IsNullOrEmpty(hash))
{
var bitmap = SKBlurHash.DeserializeBitmap(hash, Width, Height);
return (SKBitmapImageSource)bitmap;
}
return null;
}
public object? ConvertBack(object? value, Type targetType, object? parameter, CultureInfo culture)
=> throw new NotImplementedException();
}
Always show how to use the converter in XAML:
<ContentPage.Resources>
<local:BlurHashConverter x:Key="BlurHashConverter" Width="32" Height="32" />
</ContentPage.Resources>
<Image Source="{Binding BlurHash, Converter={StaticResource BlurHashConverter}}" />
cd docs
docfx build # Build docs
docfx serve _site --port 8080 # Serve locally
docfx --serve # Build and serve in one command
Verify pages render correctly:
curl -s http://localhost:8080/docs/blurhash.html | grep -o '<h1[^>]*>.*</h1>'
Use consistent language tags for syntax highlighting:
xml for XAML/XML content (not xaml - docfx highlights xml better)csharp for C# codebash for shell commandsyaml for YAML filesFor small documentation sites, use a flat TOC with section headings:
items:
- name: Overview
href: ../index.md
- name: SkiaSharp.Extended # Heading only (no href = visual separator)
- name: Blur Hash
href: blurhash.md
- name: Geometry Helpers
href: geometry.md
- name: Path Interpolation
href: path-interpolation.md
- name: SkiaSharp.Extended.UI.Maui # Heading only
- name: Confetti Effects
href: confetti.md
- name: Lottie Animations
href: lottie.md
- name: Resources # Catch-all for non-essential items
- name: Migration Guides
items:
- name: SVG Migration
href: svg-migration.md
When renaming doc files for friendlier URLs:
skblurhash.md → blurhash.mdskgeometry.md → geometry.md (if renaming)When documenting external technologies:
Always test code snippets before including in docs.
For each doc page, create a minimal test project in /tmp/:
mkdir -p /tmp/docs-code-test
cd /tmp/docs-code-test
Create .csproj:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net10.0</TargetFramework>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
</PropertyGroup>
<ItemGroup>
<ProjectReference Include="/path/to/source/SkiaSharp.Extended/SkiaSharp.Extended.csproj" />
</ItemGroup>
</Project>
Create Program.cs that exercises all code from the doc page:
// Test all code snippets from [Feature] docs
using SkiaSharp;
using SkiaSharp.Extended;
Console.WriteLine("Testing [Feature] doc code snippets...\n");
// === Quick Start: Encode ===
Console.WriteLine("1. Quick Start - Encode:");
// Copy code from docs here
// Verify it compiles and runs
// === Quick Start: Decode ===
Console.WriteLine("2. Quick Start - Decode:");
// Copy code from docs here
Console.WriteLine("\n✅ All code snippets compile and run correctly!");
Run the test:
dotnet run
Test in a separate MAUI project (see MAUI Integration Examples section).
Before finalizing a doc page:
The docs workflow (builds-docs.yml) requires:
dotnet workload install maui --source https://api.nuget.org/v3/index.json