Provides templates, style guidelines, and a complete workflow for writing MkDocs documentation, sample pages, and navigation updates for BlazorWebFormsComponents. Covers component doc structure with Web Forms vs Blazor syntax comparisons, migration guide templates, sample page creation in AfterBlazorServerSide with demo and source code sections, NavMenu.razor and ComponentList.razor updates, and README linking. Use when documenting a new or existing BWFC component, creating sample pages with escaped code blocks, updating mkdocs.yml navigation, or following the complete documentation workflow from docs to samples to README.
This skill provides guidance for writing documentation for the BlazorWebFormsComponents library. Use this when creating or updating component documentation, migration guides, or utility feature docs.
The documentation serves developers migrating ASP.NET Web Forms applications to Blazor. Every document should:
When documenting a component, use this exact structure:
# [ComponentName]
[One paragraph describing what this component does and why it exists in this library]
Original Microsoft implementation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.[componentname]?view=netframework-4.8
## Features Supported in Blazor
- [List each supported feature as a bullet point]
- [Include supported events with brief description]
- [Note any Blazor-specific enhancements]
### Blazor Notes
[Any Blazor-specific implementation details or behavioral differences]
## Web Forms Features NOT Supported
- **[FeatureName]** - [Brief explanation of why not supported or what to use instead]
- **PostBackUrl** - Not supported; Blazor uses component events instead
- **ViewState serialization** - Not needed; state is preserved in component fields
## Web Forms Declarative Syntax
```html
<asp:[ComponentName]
[All attributes from original Web Forms control]
[Alphabetically ordered]
[Include runat="server" at the end]
/>
<[ComponentName]
[Supported attributes only]
[Same order as Web Forms section for easy comparison]
/>
[Practical advice for migration] [Common pitfalls to avoid] [Performance considerations if any]
@* Description of what this example shows *@
<[ComponentName] Property="value" OnEvent="Handler" />
@code {
void Handler()
{
// Implementation
}
}
@* More complex example *@
## Writing Style Guidelines
### Tone
- Professional but approachable
- Acknowledge that migration is work, but this library helps
- Be direct about what's NOT supported rather than hiding it
### Code Examples
- Always show WORKING code that can be copy-pasted
- Include `@code` blocks with event handlers
- Use realistic property names and values
- Comment complex sections
### Web Forms Syntax Blocks
- Copy the FULL attribute list from Microsoft docs
- Include ALL attributes even if not supported (helps with migration)
- Keep attributes alphabetically ordered within logical groups
- Always include `runat="server"` at the end
### Blazor Syntax Blocks
- Show only SUPPORTED attributes
- Maintain same order as Web Forms for easy comparison
- Omit `runat` attribute (not used in Blazor)
- Use Blazor event syntax (`OnClick` not `OnClick="Handler"`)
## Migration Guide Template
```markdown
# Migrating [Feature/Pattern]
## Overview
[What this guide covers and who it's for]
## Prerequisites
- [Required knowledge]
- [Required tools/versions]
## Step-by-Step Migration
### Step 1: [Action]
**Before (Web Forms):**
```aspx
[Web Forms code]
After (Blazor):
[Blazor code]
[Explanation of changes]
[Continue pattern...]
Problem: [Description] Solution: [How to fix]
## Utility Feature Documentation Template
```markdown
# [FeatureName]
## Background
[Why this feature existed in Web Forms]
[What problem it solved]
## Web Forms Usage
```csharp
// How it was used in Web Forms
[How this library implements the feature] [Key differences from Web Forms]
// How to use in Blazor
[How to update existing code] [Recommended Blazor alternatives if applicable]
[Recommendations for properly refactoring away from this legacy pattern]
## File Naming Conventions
- Use PascalCase for component docs: `Button.md`, `GridView.md`
- Use kebab-case for guides: `migration-readiness.md`, `master-pages.md`
- Exception: `readme.md` for index pages (lowercase)
## MkDocs Integration
After creating documentation:
1. Add entry to `mkdocs.yml` in appropriate `nav:` section
2. Maintain alphabetical order within categories
3. Use descriptive nav labels matching the component name
```yaml