Skip to content

Latest commit

 

History

History
61 lines (46 loc) · 2.37 KB

README.md

File metadata and controls

61 lines (46 loc) · 2.37 KB

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