Markdown 도움말을 공통 Skia renderer로 그리고 Avalonia, WPF, WinUI 3, Uno의
화면 캔버스에 직접 표시하는 라이브러리입니다. 네 UI 프레임워크 모두 재사용 가능한
SkiaMarkdownCanvas를 제공하며, 제품 렌더링 경로에 PNG 파일을 만들지 않습니다.
네 패키지 모두 첫 실행 가이드 오버레이를 제공하며, Avalonia 패키지는 본문,
툴팁과 별도 도움말 창도 제공합니다.
MarkdownHelp.Core
├─ UI와 무관한 reader 상태
└─ IMarkdownGuideOverlay + 안내 탐색·저장·배치·공통 visual token
MarkdownHelp.Skia
├─ Markdig + RichTextKit + CSharpMath + SkiaSharp
├─ 재생 가능한 MarkdownRenderFrame (SKPicture)
├─ IMarkdownFrameCanvas (공개 adapter 계약)
└─ MarkdownCanvasSession (frame 수명·확대·extent)
├─ MarkdownHelp.Avalonia → backend SKCanvas
├─ MarkdownHelp.Wpf → SKElement
├─ MarkdownHelp.WinUI → SKXamlCanvas
└─ MarkdownHelp.Uno → SKCanvasElement
MarkdownHelp.Core는 페이지 이동과 50–400% 확대 상태를 공유합니다.MarkdownHelp.Skia는 제목, 본문, 중첩 목록, 정렬 표, 코드, 인용문, 상대 이미지, inline/display TeX 수식과 Mermaid flowchart subset을 한 번 구현합니다.IMarkdownFrameCanvas는 네 플랫폼 control의SetFrame,SetZoom,ReleaseFrame, 논리 크기 계약을 컴파일 단계에서 통일합니다.MarkdownCanvasSession은 프레임 소유권과 50–400% 확대 범위, 논리/화면 크기를 프레임워크와 무관하게 관리합니다.IMarkdownGuideOverlay와MarkdownGuideController는 열기, 이전·다음·완료, 최초 한 번 표시 상태와 카드 배치를 네 프레임워크에서 같은 방식으로 처리합니다.MarkdownGuideVisualTokens는 Avalonia 디자인을 기준으로 카드 380×500, 24px 안쪽 여백, 332px Markdown frame, 최소 34px 헤더, 12px 구역 간격, 34px 원형 표식과 공통 색상을 한 곳에서 정의합니다.MarkdownHelp.Avalonia,.Wpf,.WinUI,.Uno는 얇은 화면 어댑터이며 같은MarkdownRenderFrame을 각 프레임워크의 실제 Skia surface에 재생하고, 각 UI의 좌표·입력·컨트롤 형식에 맞는MarkdownGuideOverlay를 제공합니다.
제품 렌더링 경로에는 임시 PNG 파일이 없습니다. 확대할 때 같은 vector frame을 재생하므로 글자와 도형이 원본 bitmap 해상도에 묶이지 않습니다.
패키지는 nuget.org에 있습니다. 쓰는 UI 프레임워크의 패키지 하나만 추가하면
MarkdownHelp.Core와 MarkdownHelp.Skia는 의존성으로 함께 따라옵니다.
dotnet add package MarkdownHelp.Avalonia --prerelease
dotnet add package MarkdownHelp.Wpf --prerelease
dotnet add package MarkdownHelp.WinUI --prerelease
dotnet add package MarkdownHelp.Uno --prereleaseUI 없이 렌더링만 필요하면(서버 측 이미지 생성, 자체 캔버스 어댑터 작성 등)
MarkdownHelp.Skia만 추가해도 됩니다.
| 패키지 | 대상 프레임워크 | 내용 |
|---|---|---|
MarkdownHelp.Core |
net8.0 | reader 상태, 가이드 계약, visual token |
MarkdownHelp.Skia |
net8.0 | Markdown 레이아웃과 Skia 벡터 렌더링 |
MarkdownHelp.Avalonia |
net8.0 | 캔버스, 본문 view, 툴팁, 도움말 창, 가이드 오버레이 |
MarkdownHelp.Wpf |
net9.0-windows10.0.19041.0 | 캔버스, 가이드 오버레이 |
MarkdownHelp.WinUI |
net10.0-windows10.0.19041.0 | 캔버스, 가이드 오버레이 |
MarkdownHelp.Uno |
net9.0 | 캔버스, 가이드 오버레이 |
현재 버전은 0.1.0-alpha.6 시험판이므로 --prerelease(또는 PackageReference에
명시적 버전)가 필요합니다. 버전별 변경 내역은 CHANGELOG.md를
참고하세요. WinUI 어댑터는 SkiaSharp.Views.WinUI에 맞춰 .NET 10을
쓰며, unpackaged 앱은 현재 경계의 manifest 안내를 함께 확인하세요.
PackageReference로 직접 적을 때는 다음과 같습니다.
<PackageReference Include="MarkdownHelp.Avalonia" Version="0.1.0-alpha.6" />바로 이어지는 캔버스 사용 예와 Avalonia 도움말 사용 예가 최소 사용 코드입니다.
| Avalonia | WPF |
|---|---|
 |
 |
| WinUI 3 | Uno |
|---|---|
 |
 |
MarkdownHelpToolTip은 실제 Flyout 안에서 스크롤과 크기 조절을 지원합니다.
문서 기준 상대경로 이미지도 같은 source resolver로 읽습니다.
MarkdownGuideOverlay는 기존 화면 위에 대상 강조와 vector Markdown 설명 카드를
표시합니다. 완료·닫기 상태를 저장하고 사용자가 원할 때 다시 열 수 있습니다.
Avalonia, WPF, WinUI, Uno 구현은 모두 Core의 같은 탐색·저장 계약을 사용합니다.
네 guide demo는 GuideDemoVisualTokens의 24px 페이지 간격과 107/107/140px 동작
단추 폭을 공유합니다. 실제 오버레이는 MarkdownGuideVisualTokens의 380×500px 카드,
332px Markdown frame과 최소 34px 헤더를 사용합니다. 헤더는 고정 높이가 아니라
MinHeight로 적용해 DPI나 테마가 바뀌어도 내용이 잘리지 않습니다.
렌더링 코드는 공통이고 캔버스 형식만 프레임워크별 패키지에서 선택합니다.
using var renderer = new MarkdownHelp.Skia.SkiaMarkdownRenderer();
var frame = renderer.CreateFrame(markdown, 900);
MarkdownHelp.Skia.IMarkdownFrameCanvas canvas =
new MarkdownHelp.Wpf.SkiaMarkdownCanvas();
// Avalonia, WinUI, Uno 구현도 같은 인터페이스를 사용합니다.
canvas.SetFrame(frame, zoom: 1);
canvas.SetZoom(1.5f);SetFrame에 넘긴 frame의 소유권은 canvas로 이동합니다. 새 frame으로 교체하거나
canvas를 해제하면 이전 frame도 함께 해제됩니다.
using MarkdownHelp.Avalonia;
var source = MarkdownHelpSource.FromResource(
"avares://YourApp/Help/settings.md");
var view = new MarkdownHelpView(source);
MarkdownHelpToolTip.Attach(infoButton, source);
MarkdownHelpWindow.Show(source, "설정 도움말", ownerWindow);가이드 오버레이 구성과 상태 저장 정책은 Avalonia 패키지 설명서를 참고하세요.
각 패키지는 플랫폼의 실제 대상 컨트롤을 받는 MarkdownGuideStep과 루트 패널의
마지막 자식으로 배치하는 MarkdownGuideOverlay를 제공합니다. WPF, WinUI, Uno의
설명 본문은 SkiaMarkdownCanvas에 직접 그려지며 PNG를 만들지 않습니다.
var guide = new MarkdownHelp.Wpf.MarkdownGuideOverlay(
[
new(previousButton, "이전 페이지", "## 이전 문서로 이동합니다.", "이전 단추를 누릅니다."),
new(zoomButton, "확대", "수식과 도형도 **vector**로 확대됩니다.", "확대 단추를 누릅니다.")
]);
rootGrid.Children.Add(guide);
guide.ShowOnce("reader-guide:v1", new MarkdownHelp.Core.JsonFileMarkdownGuideStateStore(statePath));다른 프레임워크도 namespace와 대상 컨트롤 형식만 바뀌며 Show, ShowOnce,
Previous, Next, GoToStep, Close는 IMarkdownGuideOverlay의 동일한 API입니다.
네 구현은 진행률·닫기 헤더, 제목, 가변 높이 Markdown, 동작 힌트, 이전·다음 탐색의
같은 5행 카드 구조를 사용합니다. PreviousButton, NextButton, CloseButton,
StepMarkers, GuideCard도 모두 공개되어 자동화 시험과 제품 테마 조정에 쓸 수 있습니다.
공통 scrim 배치는 현재 대상 영역을 투명하게 비워 원래 컨트롤의 색과 내용을 유지하고,
나머지 화면만 어둡게 처리합니다.
# Avalonia 공통 reader 화면
dotnet run --project examples/MarkdownHelp.Avalonia.Demo
# Avalonia 첫 실행 가이드 오버레이
dotnet run --project examples/MarkdownHelp.Avalonia.GuideDemo
# Uno 첫 실행 가이드 오버레이
dotnet run \
--project examples/MarkdownHelp.Uno.Demo/MarkdownHelp.Uno.GuideDemo \
-f net9.0-desktop
# Uno Skia Desktop
dotnet run \
--project examples/MarkdownHelp.Uno.Demo/MarkdownHelp.Uno.Demo \
-f net9.0-desktopWindows에서는 다음 예제를 실행할 수 있습니다. WinUI는 .NET 10 SDK가 필요합니다.
dotnet run --project examples/MarkdownHelp.Wpf.Demo
dotnet run --project examples/MarkdownHelp.WinUI.Demo
dotnet run --project examples/MarkdownHelp.Wpf.GuideDemo
dotnet run --project examples/MarkdownHelp.WinUI.GuideDemo네 reader는 experiments/markdown-rendering의 같은 복합 Markdown fixture를 사용해
목록·표·수학식·Mermaid와 페이지 이동, 확대, 패닝, flyout을 비교합니다.
네 guide demo는 MarkdownHelp.GuideDemoSupport의 같은 세 단계 Markdown과 guide key를
사용하며, 플랫폼별 오버레이를 IMarkdownGuideOverlay로 다룹니다. 대상 강조, 전체
단계 번호, 이전·다음·완료, JSON 최초 실행 상태와 다시 보기 흐름도 동일합니다.
데모 전용 화면 치수는 GuideDemoVisualTokens, 제품 오버레이 치수와 색상은
MarkdownGuideVisualTokens가 각각 단일 기준입니다.
dotnet build src/MarkdownHelp.Core/MarkdownHelp.Core.csproj
dotnet build src/MarkdownHelp.Skia/MarkdownHelp.Skia.csproj
dotnet build src/MarkdownHelp.Avalonia/MarkdownHelp.Avalonia.csproj
dotnet build src/MarkdownHelp.Wpf/MarkdownHelp.Wpf.csproj
dotnet build src/MarkdownHelp.WinUI/MarkdownHelp.WinUI.csproj
dotnet build src/MarkdownHelp.Uno/MarkdownHelp.Uno.csproj
dotnet test tests/MarkdownHelp.Avalonia.Tests/MarkdownHelp.Avalonia.Tests.csproj
dotnet test tests/MarkdownHelp.Wpf.Tests/MarkdownHelp.Wpf.Tests.csproj
dotnet test tests/MarkdownHelp.WinUI.Tests/MarkdownHelp.WinUI.Tests.csproj
dotnet test tests/MarkdownHelp.Uno.Tests/MarkdownHelp.Uno.Tests.csproj
dotnet pack src/MarkdownHelp.Skia/MarkdownHelp.Skia.csproj -o artifacts/packages
dotnet pack src/MarkdownHelp.Avalonia/MarkdownHelp.Avalonia.csproj -o artifacts/packages
dotnet pack src/MarkdownHelp.Wpf/MarkdownHelp.Wpf.csproj -o artifacts/packages
dotnet pack src/MarkdownHelp.WinUI/MarkdownHelp.WinUI.csproj -o artifacts/packages
dotnet pack src/MarkdownHelp.Uno/MarkdownHelp.Uno.csproj -o artifacts/packages버전별 변경 내역은 CHANGELOG.md에 있습니다.
가이드 디자인 비교는 Windows에서 네 앱을 모두 1200×800으로 실행하고 단계 1과
별도 검증 단계 3을 각각 세 번 캡처해 수행했습니다. 반복 캡처는 플랫폼별로 픽셀
차이가 없었고, Avalonia 기준 WPF의 RMSE는 단계 1에서 0.1002, 단계 3에서 0.0903이었습니다.
남은 차이는 주로 각 프레임워크의 네이티브 글꼴 메트릭과 기본 컨트롤 테마입니다.
재현 스크립트와 기준은 experiments/guide-overlay-parity/windows에 있습니다.
여섯 패키지는 nuget.org Trusted Publishing(OIDC)으로 배포합니다. 장기 API 키를
저장하지 않고, v* 태그를 푸시하면 .github/workflows/publish.yml이 임시 키를 받아
push 합니다. 정책 등록과 릴리스 절차는 docs/nuget-publishing.md에
있습니다.
배포된 패키지가 실제로 동작하는지는 nuget-smoke/로
확인합니다. 리포 내부 테스트는 ProjectReference로 돌기 때문에 패키징 문제를
잡지 못합니다.
./nuget-smoke/run-smoke.sh 0.1.0-alpha.6아래 데모들도 참조만 배포 패키지로 바꿔 그대로 실행할 수 있습니다.
dotnet run --project examples/MarkdownHelp.Avalonia.Demo "-p:UseMarkdownHelpPackages=true"- 링크 hit-test와 실행 정책, 부분 텍스트 선택, 구조화된 접근성 tree는 아직 없습니다.
- Mermaid는
flowchart/graph의TD,TB,LR, 기본 node와 label 간선만 지원합니다. - WinUI 어댑터는
SkiaSharp.Views.WinUI 3.119.4의 지원 대상에 맞춰 .NET 10을 사용합니다. unpackaged 앱은 SkiaSharp 네이티브 WinRT 클래스를 application manifest에 등록해야 하며 예제의app.manifest를 기준으로 삼을 수 있습니다. - Avalonia, WPF, Uno, WinUI 예제는 Windows에서 같은 문서 화면과 직접 canvas 렌더링을 확인했습니다.