← Docs home

🎆 Sharpdown

Sharpdown is a polyglot documentation convention that enables generating markdown documentation directly from source code.

Read This First Why It Matters
Source file The comments you type.
Rendered Markdown The document that ships.
Test fixture The behavior contract.

The source and the render are a pair.

Do not optimize one while making the other worse.

The output must read cleanly, top to bottom.

Quick Start

Import-Module <module-manifest> -Force
ConvertTo-SharpDown -Language PowerShell -Path <source-file> -OutPath <output-file>

File mode is the default. Add -Recurse to mirror a directory tree.

Renderer Contract

Rule Result
Marker line Emits Markdown.
Bare marker Emits a blank line.
Declaration line Emits a fenced code block.
Everything else Drops out.

The renderer trims each line before classification. Only spaces after the marker survive into the output.

#### - top level
####     - nested once
####         - nested twice

Markers

Language Marker Carrier
PowerShell #### four hashtags
CSharp //// four slashes
JavaScript //// four slashes
Sql ---- four dashes

PowerShell keeps # for ordinary comments. C# keeps /// for XML docs. SQL keeps -- for ordinary comments.

Visual Language

Use the same landmarks as the generated docs.

Role Fragment
File title <h1 style="color: #DCA657;">🎆 Title</h1>
Symbol title <h2 style="color: #DCA657;">Verb-Noun</h2>
Inputs <b style="color: #D2A8FF;">Parameters</b>
Outputs <b style="color: #369FFF;">Returns</b>
Failures <b style="color: #C22514;">Throws</b>

Gold is navigation. Purple is input. Blue is output. Red is failure.

Never invent a new color for the same job.

File Header Pattern

#### <h1 style="color: #DCA657;">🎆 ModuleName</h1>
####
#### > One sentence on what this file is.
####
#### ---
####
#### | Function | Purpose |
#### | --- | --- |
#### | `Verb-Noun` | One line on what it does. |

Keep summary tables narrow. Two columns are usually enough.

Function Pattern

#### <h2 style="color: #DCA657;">Verb-Noun</h2>
####
function Verb-Noun {
    #### One sentence on what it does.
    ####
    #### <b style="color: #D2A8FF;">Parameters</b>
    ####
    param(
        #### - `[string]`: __Name__
        ####     - *What the parameter is.*
        [Parameter(Mandatory)][string]$Name
    )
    #### <b style="color: #369FFF;">Returns</b>
    #### - `[PSCustomObject]`
    ####     - *What comes back.*
}
#### ---

The declaration has no marker. The renderer removes the trailing {. The signature becomes a fenced block.

Parameter Shape

#### - `[type]`: __Name__
####     - *Description, italic, one sentence.*
Part Shape
Type Backticked square brackets.
Name Bold underscore.
Description Italic nested bullet.

Use one sentence per description. Use one field per row.

Return Shape

#### - `[PSCustomObject]`
####     - `[string]`: __Source__
####         - *Redacted source path.*
####     - `[int]`: __Lines__
####         - *Number of lines written.*

Return fields mirror parameters. They nest one level deeper.

Throws Shape

#### <b style="color: #C22514;">Throws</b>
#### - When `Path` is not a file.
#### - When `OutPath` is an existing directory.
if (-not (Test-Path $Path -PathType Leaf)) {
    throw "Path is not a file."
}

The guard clauses drop out. The red landmark and bullets stay.

Declaration Keywords

CSharp:

public, protected, internal, static,
abstract, sealed, override, async

JavaScript:

export, import, class, function,
async function, type, interface

PowerShell:

function, filter, class, enum,
workflow, describe, it

Sql:

CREATE, ALTER, DROP, SELECT, INSERT,
UPDATE, DELETE, GRANT, REVOKE, WITH,
COMMENT, CALL, TRUNCATE, MERGE

Use -API when the document is the wire contract. In API mode, only marker lines emit.

Pester Test Pattern

Use the same cadence as a module file.

Test Element Sharpdown Shape
File header Gold <h1> and short blockquote.
Suite Gold <h2> before Describe.
Cases Purple Cases landmark.
Assertion One bullet before each It.

Describe and It fence on their own. Write the heading, description, cases label, and assertion bullets.

Vertical Flow

Vertical flow is not sparse text.

Vertical flow is readable rendered Markdown.

Use tables when comparison is the clearest shape. Use lists when order or grouping is the clearest shape. Use code blocks when syntax is the anchor. Use whitespace when concepts need separation.

The test is the rendered page.

Regenerate

Never hand-edit generated Markdown.

Change the source comments. Then regenerate.

Import-Module <module-manifest> -Force
ConvertTo-SharpDown -Language PowerShell -Path <source-file> -OutPath <output-file>

For a tree:

ConvertTo-SharpDown -Language PowerShell -Path <source-root> -OutPath <output-root> -Recurse

Read the generated doc before calling the source done.

If a color, blank line, table, or list looks wrong, fix the marker comments in the source.

Tests

Invoke-Pester <test-root>

Grow the tests first when adding a language, marker, or declaration pattern.