markout

Category: Tools & Productivity | Uploader: richlander | Downloads: 0 | Version: v1.0（Latest）

Markout is a .NET source-generated serializer that turns objects into readable documents (Markdown, ANSI terminal, plain text). Use it whenever a CLI tool needs structured, human-readable output instead of raw `Console.WriteLine`.

Changelog: Source: GitHub https://github.com/richlander/markout

Directory Structure

Current level: Root

📁 .github/
- 📁 workflows/
  - 📄 ci.yml 4.3 KB
  - 📄 release.yml 1.7 KB
📁 docs/
- 📁 design/
  - 📄 capability-interfaces.md 12.9 KB
  - 📄 compile-time-errors.md 4.8 KB
  - 📄 data-writer-model.md 6.5 KB
  - 📄 projection.md 10.5 KB
  - 📄 shape-system.md 11.1 KB
- 📄 backlog.md 6.8 KB
- 📄 comparison-report.md 69.5 KB
- 📄 markout-view-system-design.md 6.6 KB
- 📄 mq.md 7.8 KB
- 📄 nested-lists-guide.md 11.0 KB
- 📄 specification.md 5.0 KB
- 📄 user-guide.md 27.0 KB
📁 samples/
- 📁 CanadianContent/
  - 📄 actors.json 5.2 KB
  - 📄 bars.md 614 B
  - 📄 CanadianContent.cs 20.0 KB
  - 📄 CanadianContent.csproj 1012 B
  - 📄 cities.json 382 B
  - 📄 shows.json 2.5 KB
- 📁 DateBars/
  - 📄 DateBars.cs 1.6 KB
  - 📄 DateBars.csproj 710 B
- 📁 DotNetReleases/
  - 📄 DotNetReleases.cs 3.1 KB
  - 📄 DotNetReleases.csproj 538 B
- 📁 GitHubActivity/
  - 📄 GitHubActivity.cs 4.3 KB
  - 📄 GitHubActivity.csproj 632 B
- 📁 GitHubRepo/
  - 📄 GitHubRepo.cs 9.4 KB
- 📁 HelloMarkout/
  - 📄 HelloMarkout.cs 1.0 KB
  - 📄 HelloMarkout.csproj 538 B
- 📁 LatestCves/
  - 📄 LatestCves.cs 6.5 KB
  - 📄 LatestCves.csproj 632 B
- 📁 RecordDemo/
  - 📄 RecordDemo.cs 575 B
  - 📄 RecordDemo.csproj 538 B
- 📁 Serialization/
  - 📄 AdvancedFeatures.cs 5.7 KB
  - 📄 BasicUsage.cs 1.8 KB
  - 📄 SectionFiltering.cs 2.1 KB
  - 📄 Serialization.csproj 505 B
  - 📄 ShapeGallery.cs 3.9 KB
  - 📄 ShapeWriterUsage.cs 2.9 KB
  - 📄 WriterUsage.cs 2.9 KB
- 📁 SkipNullDemo/
  - 📄 SkipNullDemo.cs 849 B
  - 📄 SkipNullDemo.csproj 538 B
- 📁 TemplateDemo/
  - 📄 cve.json 13.2 KB
  - 📄 Program.cs 3.2 KB
  - 📄 template.md 326 B
  - 📄 TemplateDemo.csproj 908 B
- 📄 Directory.Build.props 485 B
📁 src/
- 📁 MarkdownTable.Formatting/
  - 📄 ByteLineClassifier.cs 4.1 KB
  - 📄 CalculationMode.cs 394 B
  - 📄 ColumnWidthCalculator.cs 14.3 KB
  - 📄 CompactMode.cs 1.9 KB
  - 📄 DocumentFormatter.cs 1.6 KB
  - 📄 DocumentReader.cs 9.9 KB
  - 📄 FieldDocument.cs 22.7 KB
  - 📄 FieldParser.cs 7.3 KB
  - 📄 FieldValue.cs 1.6 KB
  - 📄 FormatterRegistry.cs 1.5 KB
  - 📄 FullWidthMode.cs 495 B
  - 📄 IFormatterMode.cs 535 B
  - 📄 IFormatterModeInfo.cs 520 B
  - 📄 IParameterDescriptor.cs 803 B
  - 📄 LineReader.cs 12.9 KB
  - 📄 MarkdownDocument.cs 2.1 KB
  - 📄 MarkdownTable.Formatting.csproj 428 B
  - 📄 ParameterDescriptor.cs 947 B
  - 📄 PrettyMode.cs 567 B
  - 📄 SmoothMode.cs 520 B
  - 📄 TableFormatter.cs 2.3 KB
  - 📄 TableFormatterOptions.cs 1.6 KB
  - 📄 TableParser.cs 3.2 KB
- 📁 MarkdownTable.Query/
  - 📁 Operations/
    
    📄 ITableOperation.cs 247 B
    
    📄 OrderByOperation.cs 1.3 KB
    
    📄 SelectOperation.cs 1.5 KB
    
    📄 TableOperations.cs 5.4 KB
    
    📄 WhereOperation.cs 2.4 KB
  - 📄 MarkdownTable.Query.csproj 554 B
  - 📄 QueryEngine.cs 5.6 KB
  - 📄 QueryExecutionException.cs 243 B
  - 📄 QueryParser.cs 11.4 KB
  - 📄 QueryResult.cs 1.3 KB
  - 📄 Tokenizer.cs 7.3 KB
- 📁 Markout/
  - 📁 Attributes/
    
    📄 MarkoutBoolFormatAttribute.cs 1010 B
    
    📄 MarkoutContextAttribute.cs 892 B
    
    📄 MarkoutContextOptionsAttribute.cs 1.6 KB
    
    📄 MarkoutDisplayFormatAttribute.cs 1.1 KB
    
    📄 MarkoutFormatAttribute.cs 758 B
    
    📄 MarkoutIgnoreAttribute.cs 246 B
    
    📄 MarkoutIgnoreColumnWhenAttribute.cs 1.8 KB
    
    📄 MarkoutIgnoreInTableAttribute.cs 458 B
    
    📄 MarkoutJoinAttribute.cs 968 B
    
    📄 MarkoutLinkAttribute.cs 1.0 KB
    
    📄 MarkoutMaxItemsAttribute.cs 1.4 KB
    
    📄 MarkoutPropertyNameAttribute.cs 723 B
    
    📄 MarkoutSectionAttribute.cs 2.5 KB
    
    📄 MarkoutSerializableAttribute.cs 2.8 KB
    
    📄 MarkoutShowWhenAttribute.cs 1.1 KB
    
    📄 MarkoutSkipDefaultAttribute.cs 414 B
    
    📄 MarkoutSkipNullAttribute.cs 629 B
    
    📄 MarkoutTableDisplayAttribute.cs 1.3 KB
    
    📄 MarkoutUnwrapAttribute.cs 1.1 KB
    
    📄 MarkoutValueFormatterAttribute.cs 511 B
    
    📄 MarkoutValueMapAttribute.cs 1.1 KB
  - 📁 Formatting/
    
    📄 FormatHelper.cs 897 B
    
    📄 IBlockFormatter.cs 923 B
    
    📄 ICodeBlockFormatter.cs 627 B
    
    📄 IDocumentFormatter.cs 613 B
    
    📄 IFieldFormatter.cs 1.1 KB
    
    📄 IHeadingFormatter.cs 532 B
    
    📄 IListFormatter.cs 832 B
    
    📄 IMarkoutFormatter.cs 487 B
    
    📄 IMetricsFormatter.cs 973 B
    
    📄 IStreamingTableFormatter.cs 1.3 KB
    
    📄 ITableFormatter.cs 944 B
    
    📄 ITreeFormatter.cs 521 B
  - 📄 BlockWriter.cs 1.4 KB
  - 📄 Breakdown.cs 777 B
  - 📄 Callout.cs 448 B
  - 📄 CalloutSeverity.cs 469 B
  - 📄 CodeBlockWriter.cs 1.4 KB
  - 📄 CodeSection.cs 531 B
  - 📄 Description.cs 481 B
  - 📄 DiagramFormatter.cs 3.5 KB
  - 📄 DocumentLayout.cs 540 B
  - 📄 DocumentSchema.cs 6.6 KB
  - 📄 FieldLayout.cs 1.1 KB
  - 📄 FieldWriter.cs 2.4 KB
  - 📄 HeadingWriter.cs 759 B
  - 📄 IMarkoutFormattable.cs 875 B
  - 📄 IMarkoutPropertyFormatter.cs 474 B
  - 📄 IMarkoutValueFormatter.cs 323 B
  - 📄 ListWriter.cs 1.3 KB
  - 📄 MarkdownFormatter.cs 17.9 KB
  - 📄 Markout.csproj 1.3 KB
  - 📄 MarkoutField.cs 267 B
  - 📄 MarkoutProjection.cs 9.1 KB
  - 📄 MarkoutRenderContext.cs 741 B
  - 📄 MarkoutSchemaInfo.cs 10.5 KB
  - 📄 MarkoutSerializer.cs 8.2 KB
  - 📄 MarkoutSerializerContext.cs 6.0 KB
  - 📄 MarkoutShape.cs 1.6 KB
  - 📄 MarkoutTypeInfo.cs 2.0 KB
  - 📄 MarkoutWriter.cs 30.9 KB
  - 📄 MarkoutWriterOptions.cs 4.7 KB
  - 📄 Metric.cs 284 B
  - 📄 MetricsWriter.cs 1.4 KB
  - 📄 NamingPolicy.cs 522 B
  - 📄 OneLineFormatter.cs 3.1 KB
  - 📄 PlainTextFormatter.cs 5.9 KB
  - 📄 TableWriter.cs 4.6 KB
  - 📄 TreeNode.cs 1.3 KB
  - 📄 TreeWriter.cs 1.7 KB
  - 📄 UnicodeFormatter.cs 9.9 KB
- 📁 Markout.Ansi/
  - 📄 AnsiFormatter.cs 13.5 KB
  - 📄 Markout.Ansi.csproj 682 B
  - 📄 TerminalTextWriter.cs 836 B
- 📁 Markout.Ansi.Spectre/
  - 📄 Markout.Ansi.Spectre.csproj 528 B
  - 📄 SpectreFormatter.cs 13.3 KB
  - 📄 SpectreTextWriter.cs 915 B
- 📁 Markout.Demo/
  - 📁 Data/
    
    📄 shoes.json 4.0 KB
  - 📁 output/
    
    📄 list.md 254 B
    
    📄 nested.md 2.6 KB
    
    📄 pivot.md 356 B
    
    📄 schema.md 1.6 KB
    
    📄 sections.md 592 B
    
    📄 simple.md 180 B
    
    📄 table.md 470 B
    
    📄 tree.md 713 B
  - 📄 DemoData.cs 5.5 KB
  - 📄 Demos.cs 5.4 KB
  - 📄 Markout.Demo.csproj 1.1 KB
  - 📄 Models.cs 6.7 KB
  - 📄 Program.cs 547 B
  - 📄 README.md 6.6 KB
- 📁 Markout.SourceGeneration/
  - 📁 Emitter/
    
    📄 CollectionEmitter.cs 14.1 KB
    
    📄 EmitHelpers.cs 18.8 KB
    
    📄 FieldEmitter.cs 31.4 KB
    
    📄 SerializerEmitter.cs 45.1 KB
  - 📁 Parser/
    
    📄 ContextMetadata.cs 2.7 KB
    
    📄 KnownTypeSymbols.cs 3.1 KB
    
    📄 TypeMetadata.cs 17.3 KB
    
    📄 TypeParser.cs 40.6 KB
  - 📄 DiagnosticDescriptors.cs 3.4 KB
  - 📄 Markout.SourceGeneration.csproj 1011 B
  - 📄 MarkoutSourceGenerator.cs 2.7 KB
- 📁 Markout.Templates/
  - 📄 Markout.Templates.csproj 830 B
  - 📄 MarkoutTemplate.cs 9.9 KB
  - 📄 TemplateBinding.cs 2.8 KB
  - 📄 TemplateNode.cs 1.4 KB
  - 📄 TemplateParser.cs 7.2 KB
📁 tests/
- 📁 MarkdownTable.Tests/
  - 📄 DocumentReaderTests.cs 11.1 KB
  - 📄 FieldDocumentTests.cs 14.2 KB
  - 📄 FieldParserTests.cs 8.1 KB
  - 📄 FieldValueTests.cs 5.1 KB
  - 📄 MarkdownTable.Tests.csproj 687 B
  - 📄 QueryEngineTests.cs 11.2 KB
  - 📄 TokenizerAndParserTests.cs 16.8 KB
- 📁 Markout.Templates.Tests/
  - 📄 BindContextTests.cs 1.7 KB
  - 📄 BindFieldsTests.cs 4.8 KB
  - 📄 Markout.Templates.Tests.csproj 954 B
  - 📄 MarkoutTemplateTests.cs 8.6 KB
  - 📄 TableFormatterTests.cs 4.5 KB
  - 📄 TemplateParserTests.cs 5.2 KB
- 📁 Markout.Tests/
  - 📄 AnsiFormatterTests.cs 6.8 KB
  - 📄 BuildResultsTests.cs 23.1 KB
  - 📄 CompileTimeErrorTests.cs 32.2 KB
  - 📄 DiagramFormatterTests.cs 2.8 KB
  - 📄 FormatAttributeTests.cs 6.5 KB
  - 📄 FormatExamplesTests.cs 15.2 KB
  - 📄 GeneratedCodeTests.cs 5.2 KB
  - 📄 IgnoreColumnWhenTests.cs 14.0 KB
  - 📄 IgnoreFieldsTests.cs 1.7 KB
  - 📄 ListRenderingStrategyTests.cs 16.6 KB
  - 📄 Markout.Tests.csproj 1.0 KB
  - 📄 MarkoutWriterTests.cs 44.6 KB
  - 📄 NestedStructureTests.cs 61.1 KB
  - 📄 NullableAndTitleTests.cs 11.0 KB
  - 📄 OneLineFormatterTests.cs 4.9 KB
  - 📄 PartialHookTests.cs 851 B
  - 📄 PivotTableTests.cs 22.3 KB
  - 📄 ProjectionTests.cs 28.8 KB
  - 📄 RenderingStrategyTests.cs 26.2 KB
  - 📄 SectionConstantsTests.cs 2.6 KB
  - 📄 SerializerTests.cs 69.5 KB
  - 📄 ShapeSupportTests.cs 7.8 KB
  - 📄 UnicodeFormatterTests.cs 13.4 KB
- 📁 mq-bench/
  - 📄 mq-bench.csproj 740 B
  - 📄 package.json 1.1 KB
  - 📄 package.md 996 B
  - 📄 Program.cs 19.9 KB
  - 📄 releases.json 745 B
  - 📄 releases.md 491 B
📁 tools/
- 📁 markout-template/
  - 📄 markout-template.csproj 615 B
  - 📄 Program.cs 2.0 KB
- 📁 mq/
  - 📄 mq.csproj 472 B
  - 📄 Program.cs 3.6 KB
- 📁 ttt/
  - 📄 CommandLineOptions.cs 260 B
  - 📄 DynamicArgumentParser.cs 3.7 KB
  - 📄 Program.cs 2.5 KB
  - 📄 ttt.csproj 449 B
📄 .gitignore 7.8 KB
📄 .markdownlint-cli2.jsonc 64 B
📄 .markdownlint.yaml 852 B
📄 AGENT.md 1.1 KB
📄 Directory.Build.props 781 B
📄 Markout.sln 20.7 KB
📄 nuget.config 278 B
📄 README.md 15.3 KB
📄 SKILL.md 8.7 KB

SKILL.md

# Markout — Coding Agent Integration Guide

Markout is a .NET source-generated serializer that turns objects into readable documents (Markdown, ANSI terminal, plain text). Use it whenever a CLI tool needs structured, human-readable output instead of raw `Console.WriteLine`.

## Installation

```bash
dotnet add package Markout
```

This single package includes the source generator. No additional packages needed for Markdown or plain text output.

For ANSI terminal output with Spectre.Console:

```bash
dotnet add package Markout.Ansi.Spectre
```

## Core Pattern

Every markout integration follows three steps:

### 1. Define a model

Annotate a class or record with `[MarkoutSerializable]`. Scalar properties become fields. `List<T>` properties become tables. Built-in types like `Metric`, `Breakdown`, `Callout`, and `TreeNode` produce charts, bars, alerts, and trees.

```csharp
using Markout;

[MarkoutSerializable(TitleProperty = nameof(Title))]
public class ToolReport
{
    public string Title { get; set; } = "";
    public string Status { get; set; } = "";
    public int ItemCount { get; set; }

    [MarkoutSection(Name = "Results")]
    public List<ResultRow>? Results { get; set; }
}

[MarkoutSerializable]
public class ResultRow
{
    public string Name { get; set; } = "";
    public string Value { get; set; } = "";
}
```

### 2. Define a context

Create a partial class that registers your models for source generation:

```csharp
[MarkoutContext(typeof(ToolReport))]
[MarkoutContext(typeof(ResultRow))]
public partial class ToolContext : MarkoutSerializerContext { }
```

### 3. Serialize

```csharp
MarkoutSerializer.Serialize(report, Console.Out, ToolContext.Default);
```

That's it. The output is Markdown by default.

## Attribute Reference

### Type-level attributes

| Attribute | Purpose | Example |
|---|---|---|
| `[MarkoutSerializable]` | Mark type for serialization | `[MarkoutSerializable(TitleProperty = "Name")]` |
| `[MarkoutContext(typeof(T))]` | Register type with context | `[MarkoutContext(typeof(MyReport))]` |

`MarkoutSerializable` properties:

- `TitleProperty` — Property to render as the H1 heading
- `DescriptionProperty` — Property to render as a paragraph below the heading
- `AutoFields` — Auto-render scalar properties as fields (default: `true`)
- `FieldLayout` — `Table` (two-column, default), `Inline` (pipe-separated), `Bulleted`, `Numbered`, or `Plain` (bare lines)

### Property-level attributes

| Attribute | Purpose | Example |
|---|---|---|
| `[MarkoutSection(Name = "...")]` | Render as a `## Heading` section | `[MarkoutSection(Name = "Errors")]` |
| `[MarkoutPropertyName("...")]` | Custom display name | `[MarkoutPropertyName("Open Issues")]` |
| `[MarkoutDisplayFormat("...")]` | Format string | `[MarkoutDisplayFormat("{0:N0}")]` |
| `[MarkoutBoolFormat("✓", "✗")]` | Custom bool display | `[MarkoutBoolFormat("Yes", "No")]` |
| `[MarkoutSkipNull]` | Hide when null | |
| `[MarkoutSkipDefault]` | Hide when default value | |
| `[MarkoutShowWhen(nameof(Flag))]` | Conditional rendering | `[MarkoutShowWhen(nameof(HasErrors))]` |
| `[MarkoutIgnore]` | Exclude from output | |
| `[MarkoutIgnoreInTable]` | Exclude from table columns | |
| `[MarkoutMaxItems(N)]` | Truncate long lists | `[MarkoutMaxItems(10)]` |
| `[MarkoutLink(nameof(Url))]` | Render as hyperlink | `[MarkoutLink(nameof(HtmlUrl))]` |
| `[MarkoutUnwrap]` | Inline collection without section heading | |
| `[MarkoutIgnoreColumnWhen(...)]` | Conditionally hide table column | |
| `[MarkoutValueMap("k=v", ...)]` | Map values to display strings | |

### Section properties

`[MarkoutSection]` supports:

- `Name` — Section heading text
- `Level` — Heading level (default: 2 for `##`)
- `GroupBy` — Group items by a property value
- `ShowWhenProperty` — Boolean property controlling visibility
- `IgnoreProperty` — Comma-separated column names to hide

## Built-in Shape Types

Use these types as properties on your model to get rich output:

```csharp
// Bar chart — comparative quantities
[MarkoutSection(Name = "Performance")]
[MarkoutIgnoreInTable]
public List<Metric>? Metrics { get; set; }
// Usage: new Metric("Build Time", 4.2)

// Stacked bar — proportional composition
[MarkoutSection(Name = "Distribution")]
[MarkoutIgnoreInTable]
public List<Breakdown>? Distribution { get; set; }
// Usage: new Breakdown("By Type", [new Segment("Critical", 3), new Segment("Low", 12)])

// Alert box
[MarkoutIgnoreInTable]
[MarkoutSkipDefault]
public Callout Warning { get; set; }
// Usage: new Callout(CalloutSeverity.Warning, "3 issues found")

// Tree hierarchy
[MarkoutIgnoreInTable]
public List<TreeNode>? Dependencies { get; set; }
// Usage: new TreeNode("root", [new TreeNode("child1"), new TreeNode("child2")])

// Term + explanation list
[MarkoutSection(Name = "Glossary")]
[MarkoutIgnoreInTable]
public List<Description>? Terms { get; set; }
// Usage: new Description("API", "Application Programming Interface")

// Code block
[MarkoutIgnoreInTable]
public CodeSection? SourceCode { get; set; }
// Usage: new CodeSection("csharp", "public class Foo { }")
```

## Choosing a Formatter

```csharp
// Markdown (default) — documentation, LLM output, reports
MarkoutSerializer.Serialize(report, Console.Out, context);

// Markdown with explicit formatter
MarkoutSerializer.Serialize(report, Console.Out, new MarkdownFormatter(), context);

// Spectre terminal — colored, interactive
using Markout.Ansi.Spectre;
using Spectre.Console;
MarkoutSerializer.Serialize(report, Console.Out, new SpectreFormatter(AnsiConsole.Console), context);

// One-line — compact table, grep-friendly
MarkoutSerializer.Serialize(report, Console.Out, new OneLineFormatter(), context);

// One-line with section filter — show only one table
var options = new MarkoutWriterOptions
{
    IncludeDescription = false,
    IncludeSections = new HashSet<string> { "Results" }
};
MarkoutSerializer.Serialize(report, Console.Out, new OneLineFormatter(), context, options);

// Plain text — log files, piped output
MarkoutSerializer.Serialize(report, Console.Out, new UnicodeFormatter(), context);
```

## Common Recipe: JSON API to Report

This is the most common pattern — fetch JSON, project to a model, serialize:

```csharp
using System.Text.Json;
using System.Text.Json.Serialization;
using Markout;

// 1. Fetch and deserialize
using var http = new HttpClient();
var json = await http.GetStringAsync("https://api.example.com/data");
var data = JsonSerializer.Deserialize(json, ApiJsonContext.Default.ApiResponse)!;

// 2. Project to model
var report = new Report
{
    Title = data.Name,
    Count = data.Items.Count,
    Items = data.Items.Select(i => new ItemRow
    {
        Name = i.Name,
        Status = i.Status
    }).ToList()
};

// 3. Serialize
MarkoutSerializer.Serialize(report, Console.Out, ReportContext.Default);

// --- Model ---
[MarkoutSerializable(TitleProperty = nameof(Title))]
public class Report
{
    public string Title { get; set; } = "";
    public int Count { get; set; }

    [MarkoutSection(Name = "Items")]
    public List<ItemRow>? Items { get; set; }
}

[MarkoutSerializable]
public class ItemRow
{
    public string Name { get; set; } = "";
    public string Status { get; set; } = "";
}

[MarkoutContext(typeof(Report))]
[MarkoutContext(typeof(ItemRow))]
public partial class ReportContext : MarkoutSerializerContext { }

// --- JSON Model (separate from report model) ---
public class ApiResponse { public string Name { get; set; } = ""; public List<ApiItem> Items { get; set; } = []; }
public class ApiItem { public string Name { get; set; } = ""; public string Status { get; set; } = ""; }

[JsonSerializable(typeof(ApiResponse))]
internal partial class ApiJsonContext : JsonSerializerContext { }
```

## Key Principles

1. **Data models work directly with Markout.** In the simplest case, your data model is your Markout model — no separate projection layer needed. For more complex scenarios (e.g., combining multiple API responses), a dedicated report model is fine, but it's still just a data model.
2. **Attributes describe data relationships, not visuals.** Say "this is a measurement" (`Metric`), not "draw a bar."
3. **Register every type.** Every class used in serialization needs `[MarkoutSerializable]` and must be registered via `[MarkoutContext(typeof(T))]` on the context.
4. **The context must be `partial`.** The source generator fills in the implementation.
5. **`List<T>` → table, scalar → field.** The type system drives rendering. A `List<MyRow>` automatically becomes a table; a `string` or `int` property becomes a key-value field.
6. **Sections group content.** Use `[MarkoutSection(Name = "...")]` on any property to create a `## Heading` above it.
7. **Use `[MarkoutIgnoreInTable]`** on properties that aren't tabular (metrics, breakdowns, callouts, trees) to prevent them from being treated as table columns.

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

markout

Directory Structure

SKILL.md

Report

Notice