Turn your .NET library into a documentation website.
Owl reads your C# or Visual Basic project and builds a searchable site with a page for every type.
You need .NET SDK 8.0+ and Node 18+.
dotnet tool install --global McNeel.Owlowl serve MyLib.csprojOpen http://localhost:8080. Edit your docs and refresh to see the changes.
owl build MyLib.csproj --out ./publicUpload the public folder to any web host.
If the site lives under a path, such as https://example.com/api/mylib, say so:
owl build MyLib.csproj --out ./public --base /api/mylib --site-url https://example.comowl serve MyLib.csproj MyLib.Extras.csproj --name "MyLib"Links between the projects just work.
Group types into categories with a <category> tag:
/// <summary>Saves files.</summary>
/// <category>Storage</category>
public class FileStore { }Then put Markdown files in a docs/api folder next to where you run owl:
docs/api/MAIN.md home page
docs/api/logo.svg header icon
docs/api/MyLib/MAIN.md MyLib's page
docs/api/MyLib/Storage.md the Storage category's page
docs/api/MyLib/SORT.txt category order, optional
The sidebar lists your categories, and owl shows a placeholder for any page you haven't written yet.
Categories are listed alphabetically. To choose the order, list them one per line in SORT.txt:
Storage
Shapes
Categories you leave out follow, alphabetically.
Pages somewhere else? Use --docs path/to/pages.
Pages can include diagrams. Install d2 first:
```d2
Code -> Compile -> Run
```Pages can also include math:
The area of a circle is $\pi r^2$.Pages can link to your API. Write the name the way you would in <see cref="..."/>:
[FileStore](xref:FileStore) saves files. Call [](xref:FileStore.Read(string)) to read one back.Leave the text empty and owl fills in the name. Qualify a name that matches more than one thing, as in
xref:MyLib.Storage.FileStore, or give its doc id, as in xref:M:MyLib.FileStore.Read(System.String).
/// <summary>Saves files.</summary>
/// <since>2.1</since>
public class FileStore { }owl build MyLib.csproj --api-versions 3,2,1Readers pick a version from the header and see what existed up to the next version listed: picking 2 shows
what 2.1 added, but not what 3 added. Picking an older version adds it to the address, as ?version=2, so a
link to the page opens on that version; without it, a page opens on the newest.
The header's What's New link lists what the picked version added and made obsolete, up to the next version
listed. Its Compare with menu picks an older version to measure from instead, which opens
whatsnew/?compare=8.4...8.12: what came after 8.4, up to and including 8.12. Any two versions can be typed there.
owl build MyLib.csproj --source-refs https://github.com/me/mylib/blob/mainEvery type and member links to the line it is declared on.
If your library uses types from another library that is also documented with owl:
owl build MyPlugin.csproj --link MyLib=/api/mylibThose types now link to the other site. .NET types link to Microsoft Learn automatically.
Put your site's own bar and footer on every page, so readers can get back to the rest of it:
owl build MyLib.csproj --site-header header.html --site-footer footer.htmlBoth files are plain HTML snippets placed as given. Owl's stylesheet resets margins and padding on every element,
so their styles must set whatever they rely on. Pages opened with ?plain leave them out.
The header can also hold owl's own controls. Put a mark where each one goes and owl draws no bar of its own:
<header class="site-header">
<!-- owl:sidebar-toggle -->
<a href="/">My Site</a>
<nav>...</nav>
<!-- owl:search -->
<!-- owl:theme -->
</header>| Mark | What Goes There |
|---|---|
<!-- owl:sidebar-toggle --> |
The sidebar's show/hide button. Empty with --sidebar-toggle sidebar |
<!-- owl:search --> |
The search box, with the assembly and version pickers unless owl:pickers is marked too |
<!-- owl:pickers --> |
The assembly and version pickers on their own, e.g. beside your site's own search |
<!-- owl:theme --> |
The light/dark switch. Leave it out if your site has its own; set data-theme on <html> to keep owl in step |
- Use each mark at most once. Owl warns about repeated or misspelled marks.
- A control with no mark is left out. With any mark, owl's site title and home link are left out too.
- Owl's controls keep owl's header colours, so they suit a dark bar best. Restyle them in your header's CSS if not.
--sidebar-toggle sidebar moves the sidebar button into the corner of the sidebar, for a header that is shared with
pages that have no sidebar.
Moving from Sandcastle or docify? Old page addresses can redirect to the new pages:
owl build MyLib.csproj --sandcastle # html/T_MyLib_Storage.htm
owl build MyLib.csproj --docify # mylib.storage/ and mylib.storage/readEach old address gets a page that forwards the reader. If your host can send redirects itself, answer from
redirects.json in the output instead. It maps each old address, lower case and without a trailing slash, to its
new one. Add the request's query to the new address's own.
A member's address reads type/mylib.storage/?member=read#read, so a pasted link can preview as that member
rather than its type. A plain file host previews it as the type. To preview the member, build with --server:
owl build MyLib.csproj --base /api/mylib --server -o appThe site goes in app/site, with a node server beside it. Push app to any node host, Heroku included, and it
starts with npm start on the port the host gives it. It also redirects the old addresses of --sandcastle and
--docify.
owl verify MyLib.csprojLists undocumented API, and fails on broken <see cref="..."/> links and broken xref: links in your pages.
| Command | Option | What It Does |
|---|---|---|
| all | --name <text> |
Site name |
| all | --tfm <tfm> |
Framework to document, e.g. net48 |
| all | -c <name> |
Build configuration, e.g. Release |
| serve | --port <n> |
Port to use (default 8080) |
| build | --out <dir> |
Where to write the site |
| serve, build | --docs <dir> |
Folder of your own pages |
| serve, build | --logo <file> |
Header icon |
| serve, build | --favicon <file> |
Browser tab icon |
| serve, build | --site-header <file> |
HTML above the header on every page, e.g. a parent site's bar. See Publish Inside Another Site |
| serve, build | --site-footer <file> |
HTML at the end of every page's content |
| serve, build | --sidebar-toggle <header|sidebar> |
Where the sidebar's show/hide button goes; sidebar docks it at the tree column's corner (default header) |
| serve, build | --skip-undocumented |
Hide anything without a summary |
Run owl --help to see all options.
owl/is the command-line toolowl-gen/reads projects and writes the docs dataowl-site/turns that data into the website
Run it from source:
dotnet run --project owl -- serve MyLib.csprojDesign decisions are explained in NOTES.