sandcastle-md — Your API reference on GitHub

sandcastle-md converts your SHFB-generated HTML website to Markdown.

• Browse your API reference on GitHub.com or using any tool that supports Markdown
• Host your API reference on GitHub Pages, using your own layout and fully integrated with your site

Additionaly, sandcastle-md makes the following changes to SHFB's output:

• Transforms the flat topic file structure to a hierarchical, one directory per namespace/type
• Excludes topics that group members into categories e.g. Properties, Methods, Overloads, etc.

Project Settings

Open your SHFB project and make sure the following settings are in place:

• Build
  • Uncheck Clean intermediate files after a succesful build
    <CleanIntermediates>False</CleanIntermediates>
  • Uncheck Indent rendered HTML
    <IndentHtml>False</IndentHtml>
• Help File
  • Set Topic file naming method to Member name
    <NamingMethod>MemberName</NamingMethod>
  • Set Presentation Style to VS2010
    <PresentationStyle>VS2010</PresentationStyle>
  • Check Include root namespace container and set the title to something like <project name> Namespaces
    <RootNamespaceContainer>True</RootNamespaceContainer>
<RootNamespaceTitle>{Project Name} Namespaces</RootNamespaceTitle>
• Help 1/Website
  • Set Website SDK link type to Online links to MSDN help topics

Converting to Markdown

Build your SHFB project (if you haven't already):

MSBuild.exe <your .shfbproj project>

Restore NuGet packages and build sandcastle-md:

.\packages\restore.ps1
MSBuild.exe .\sandcastle-md.sln

Before executing it's recommended to clear any previous output, to make sure any deleted topics do not remain:

rm <output path> -Recurse

Finally, execute:

.\src\sandcastle-md\bin\Debug\sandcastle-md.exe <source website path> [output path]

Examples

• DbExtensions (GitHub.com)
• DbExtensions (GitHub Pages)
• MvcCodeRouting