# Sandcastle Help File Builder: the Windows tool that outlived Microsoft Sandcastle > EWSoftware took over a Microsoft project abandoned in 2012 and turned it into a GUI plus MSBuild pipeline for generating .NET help files from XML comments, MAML and now Markdown. **EWSoftware/SHFB** — Sandcastle Help File Builder (SHFB). A standalone GUI, Visual Studio integration package, and MSBuild tasks providing full configuration and extensibility for building help files with the Sandcastle tools. - Repository: https://github.com/EWSoftware/SHFB - Stars: 2,249 · Forks: 379 - Language: C# - License: NOASSERTION - Published: 2026-10-06 · Updated: 2026-10-06 · Language: en - Canonical page: https://hysenlabs.com/projects/ewsoftware-shfb ## Two pieces that do different jobs, and why the split matters The README draws the distinction before it draws anything else, and getting it straight saves a lot of confusion. The project is composed of two parts. The Sandcastle tools create help files for managed class libraries, and they are command-line based with, in the README's own words, no GUI front-end, no project management features and no automated build process. The Sandcastle Help File Builder is the layer that fills those gaps: it provides the missing NDoc-like features, adds a standalone GUI and command line tools that build a help file in an automated fashion, and ships a Visual Studio integration package so help projects can be created and managed from inside the IDE. That means the raw tools are the engine and SHFB is the vehicle around it. If you are scripting a build in CI, the interesting question is which of those two halves you actually need, because the command-line surface of the tools is not the same thing as a headless build system and the README does not pretend otherwise. SHFB does have a command line mode, but the documentation burden of driving it lives in the project's own help, not in the README. The history explains why the split survived. Sandcastle was created by Microsoft in 2006, the last official Microsoft release was June 2010, it was hosted on CodePlex until October 2012, and Microsoft declared support and development ceased in October 2012. The tools were merged into the SHFB project and all further work happens there. Anything you remember about Microsoft Sandcastle predates the fork. ## API topics from XML comments and reflection, not from a parser The mechanism behind API reference topics is worth understanding, because it explains both what SHFB does well and where it stops. The README describes a two-part process: the Sandcastle tools take the XML comments embedded in your source code and combine them with the syntax and structure of the types, which is acquired by reflecting against the associated .NET Framework assemblies. In other words, the prose comes from your doc comments and the structure comes from the compiled binary. Consequences follow from that design. Your assembly has to be built and locatable before help can be generated, which is why the project insists on turning on XML comment output in your project settings and keeping the XML file next to the DLL. It also means the help reflects what you actually shipped rather than what you intended to ship, which is a genuine advantage over a generator that parses source text. Type members that were never documented still appear, usually with a placeholder, because reflection does not care whether you wrote a summary. The practical constraint is the .NET Framework wording in that sentence, which appears in a project that now installs a Visual Studio extension package for VS 2022 or later. The README is not a specification of which target frameworks are supported, so anyone on modern .NET should read the installation instructions page rather than assume parity. Conceptual topics take a different path entirely, described next. ## Conceptual topics: MAML for years, Markdown since December 2025 Conceptual content is the part you author by hand. Historically that meant Microsoft Assistance Markup Language, a verbose XML dialect designed for the Help 1 compiler that predates it, and which still ships as schemas so the IDE can validate and complete your markup. Release v2025.12.18.0, published on 2025-12-19, states that the release implements support for using Markdown for conceptual content rather than MAML. That is a recent and real change, and it is the kind of decision that tells you something about the direction of the tool. Both paths remain, and the presence of `IgnoredWords.dic` at the repository root hints at the tooling around them: a dictionary for spell checking documentation text during the build, the kind of file that only makes sense if prose is checked as part of producing output. The repository also carries `Documentation/`, which is the project's own help built by the same machinery it asks you to use, making it the most complete worked example available. For MAML specifically, the Visual Studio extension includes schemas and an optional set of snippets for inserting common MAML elements while you type. That is a real quality-of-life feature and also a signal about the audience: the tool is tuned for authors working inside Visual Studio, on Windows, with the MAML structure on screen. Someone authoring documentation in a plain text editor on Linux is not the case this was designed for. ## Installing means installing other tools first The README is unusually direct about this. It points at a separate Installation Instructions page for information about the required set of additional tools that need to be installed, where to get them, and how to make sure everything is configured correctly, and adds that the guided installer walks through the installation steps itself. The release notes confirm the shape of that package: you download a ZIP, extract it, and run `SandcastleInstaller.exe`, which then installs the core components, the Visual Studio extension package and extras. Two details in the release notes are the kind of thing that saves an afternoon. Both v2026.3.29.0 and v2026.1.20.0 open with a warning that on some systems the ZIP content is blocked and the installer will fail to run, with the fix being to right-click the ZIP, open Properties, and click Unblock if the button is present. Windows marks files downloaded from the internet as coming from another computer, and a blocked executable simply refuses to start with an unhelpful message. Separately, both releases list a Help 1 compiler check with instructions on where to download it and how to install it if you need it, meaning the installer detects whether an old compiler is present and can help you get one. So the install is a guided sequence rather than a single package, and the README itself defers the details. Expect to read the installation page before anything else. ## Reading the repository layout to understand the build The top-level entries tell you more than the README does about how this thing is produced. `SHFB/` holds the application source. `MasterBuild.bat` is the batch script that drives a build on Windows, which is a plain statement of the platform constraint. `NuGet/` implies the output is packaged as NuGet packages, `Deployment/` holds what ships, and `ThirdPartyTools/` records the external tools the build depends on rather than pretending they are vendored. `TestCaseProject/` is the one entry worth pausing on for anyone evaluating quality. A documentation generator needs a corpus of documented code to test against, and keeping a dedicated sample project in the repository is the practice that makes regression testing possible in this domain. It also gives a new contributor a working example without inventing one. Two version-numbering notes. The releases follow a date-based scheme rather than semver: v2025.12.18.0, v2026.1.20.0, v2026.3.29.0. And the repository carries a `LICENSE` file, though the project's own metadata does not report a recognised SPDX identifier, so if licence terms matter to your organisation you should read that file rather than assume from a badge. The default branch is master and the primary language is C#. ## Where it stops being the right tool The honest limitation is that SHFB is a Windows desktop tool for a specific legacy help format, and the project does not pretend otherwise. The whole chain runs through Visual Studio integration, a Windows installer executable, a batch build script and the Help 1 compiler family of output formats. A team that needs documentation generated on a Linux CI runner should read the command-line documentation before committing, because the README says the command-line mode exists but says nothing about its platform behaviour, and nothing in the repository layout suggests cross-platform support. The second limitation is competitive. DocFX is the modern default for .NET documentation, it is cross-platform, it is command-line first and it renders to a modern site rather than a compiled help file. If your goal is a browsable documentation website, SHFB solves a problem you probably do not have. It wins where the target really is a help file: offline help, a CHM, Help 1 output, or an enterprise toolset that consumes help in that format. The third is that the useful documentation is not on the repository front page. Every route out of the README goes to the project's own site: a getting started section, an installation page, an FAQ, a MAML guide and an XML comments guide. That is normal for a mature Windows tool and it means you will be reading hosted HTML rather than a Markdown file. The last push was on 2026-06-27, and the most recent release before that was v2026.3.29.0 on 2026-03-29, so the project is still being worked on. ## Conclusion SHFB is the right answer for a Windows team shipping a .NET library with a public API and no documentation pipeline, and the wrong answer for almost everything else, including a modern cross-platform SDK with DocFX or XML docs published to a docs site. What the project has proven over more than a decade of post-Microsoft releases is that documentation tooling survives its original sponsor when someone keeps shipping it. The practical first step is the Getting Started topic linked from the README, because the setup burden lives in the additional tools it asks you to install, and the build itself is only the second half of the work. ## FAQ ### Is Sandcastle Help File Builder free and open source? The repository is public and its source is readable, and the root of the tree carries a LICENSE file. The project's own metadata does not report a recognised SPDX licence identifier, so the terms in that file are what govern use, and organisations with a licence review process should read it rather than rely on an assumption. ### Does Sandcastle Help File Builder work on Linux or macOS? Nothing in the project suggests it does. Installation runs through a Windows executable called SandcastleInstaller.exe, the Visual Studio extension package targets VS 2022 or later, and the repository builds itself through a batch script named MasterBuild.bat. The README does document a command-line mode, but it says nothing about platform behaviour, so check that documentation before planning a Linux build. ### Can Sandcastle generate help from Markdown instead of MAML? Yes. Release v2025.12.18.0 from December 2025 states that it implements support for using Markdown for conceptual content rather than MAML. MAML support remains, along with Visual Studio schemas and optional snippets for inserting common MAML elements while editing. ### Why did the installer fail to start after extracting the ZIP? Windows blocks files downloaded from the internet, so the extracted executable can be marked as coming from another computer and refuse to run. Both v2026.3.29.0 and v2026.1.20.0 open with the same instruction: right-click the ZIP, select Properties, and click Unblock in the lower right of the General tab if the button is there. ## Sources - [EWSoftware/SHFB on GitHub](https://github.com/EWSoftware/SHFB) - [Issues](https://github.com/EWSoftware/SHFB/issues) - [README](https://github.com/EWSoftware/SHFB/blob/master/README.md) - [Releases](https://github.com/EWSoftware/SHFB/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ewsoftware-shfb