Sharpdown

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

Install

Install-Module Sharpdown -Scope CurrentUser

Convert a single source file to Markdown.

Import-Module Sharpdown
ConvertTo-SharpDown -Language CSharp -Path .\src\Widget.cs -OutPath .\Generated\Docs\Widget.md

Mirror a source tree.

-Recurse walks the tree, skips build output, and rebuilds the folder layout

ConvertTo-SharpDown -Language JavaScript -Path .\ -OutPath .\Generated\Docs\ -Recurse

How it works

Each language marks a doc comment with a four-character prefix. Lines that start with the marker have the marker stripped and pass through as Markdown. Lines matching the language's declaration pattern are wrapped in a fenced code block. Everything else falls away.

Language	Marker	Fence	Extensions
CSharp	////	csharp	.cs
Sql	----	sql	.sql
JavaScript	////	javascript	.js, .mjs, .ts, .tsx
PowerShell	####	powershell	.ps1, .psm1

Functions

Function	Purpose
ConvertTo-SharpDown	Convert a single source file or a tree of sources to Markdown.

Development

The suite is Pester 5. The docs are regenerated by the module's own ConvertTo-SharpDown.

Command	What it does
Invoke-Pester .\Tests	Run the Pester 5 unit suite.
Test-ModuleManifest .\Sharpdown.psd1	Validate the manifest.
ConvertTo-SharpDown -Language PowerShell -Path . -OutPath .\docs -Recurse	Regenerate the SharpDown Markdown under docs.

License

MIT. See LICENSE.