A Short Introduction

When I started working on Wyam about 2 years ago, a primary design goal (probably the primary goal) was to create a general-purpose static generator that could be easily adapted to any sort of content, from the most complicated web site to output that isn't web-based at all. I was frustrated with both the lack of a popular and robust generator in the .NET ecosystem (why should Ruby and Node get all the fun?) and also with the limitations of the generators that do exist on other platforms. Nearly all of them favor strong conventions and patterns and while many are extensible, creating experiences that differ too greatly from what's expected becomes challenging fast (a notable exception to this is Metalsmith, which is similar in spirit to Wyam).

If you look at Wyam as a generator toolkit, a tool to build the perfect static generator for your specific purpose, this concept becomes clearer. Jessica can use Wyam to create a generator for her marketing site, while Marcus can use it to create a generator for his blog, and you can use it to create a generator for that eBook you've been working on. Wyam assumes nothing about the domain and output and instead provides building blocks and a framework for your static generator.

Practically speaking however, there are a number of standard patterns. Blogs are a great example. Every blog typically has some combination of posts, archives, and tags or categories. To accommodate these sorts of uses the notion of a recipe was always part of the plan (it was literally issue #1) and their implementation was introduced about six months ago with the first Blog recipe. This turns Wyam into a powerful blogging static generator if you want it to be.

Even with recipes and blog support, it was clear that the potential of this concept hadn't been realized yet. Today I am thrilled to announce the culmination of 2 years of hard work by presenting the Docs recipe. This recipe lets you easily build documentation for your projects including a blog, content/Wiki, and automatically generated API docs from .NET sources or assemblies that rivals anything produced by doc-specific generators. Perhaps more importantly it realizes the original vision of creating a static generation toolkit and then using the building blocks to create amazing purpose-specific generators.

The Docs Recipe

As with all Wyam recipes, the docs recipe is designed to get you up and running quickly. In the most basic scenario, just download Wyam and scaffold a new documentation site:

wyam new -r Docs

This will create some sample pages like a wiki and blog post. You can edit these pages, add more, and customize your site using any editor and then run the following to build and preview it:

wyam -r Docs

Wikis and blogs are cool, but what really makes this recipe special is that it has full support for API documentation from .NET source files and assemblies. By default the recipe will look in a src folder adjacent to your input folder (the actual default globbing pattern for locating source files is "src//{!bin,!obj,!packages,!*.Tests,}//*.cs"). This can be easily changed along with many other settings. Once the recipe knows where to look for your source files, you'll see a special "API" section in your documentation with really nice looking API pages.

Some of the other features of the recipe include:

• Nested documentation content and wiki pages.
• Blog posts with optional category and author.
• Paged blog archives for posts, categories, authors, and dates.
• Posts and pages can be in Markdown or Razor.
• API documentation from source files.
• API documentation from assemblies (with or without XML documentation file from MSBuild).
• Static site searching for API types.
• Meta-refresh redirects and/or a Netlify redirect file.
• RSS, Atom, and/or RDF feeds.
• Support for namespace XML documentation comments.
• Support for <inheritdoc>, CDATA, and other XML documentation comment conventions.

Visit the Docs recipe section on the Wyam site for more information.

More Power!

But why would you want to use this instead of one of the many excellent documentation-specific generators like DocFx? The most compelling answer to that question is the customization abilities Wyam provides. Because a recipe in Wyam is just a combination of the same modules and pipelines you could have built on your own, bending them to your will is easy once you understand what's going on behind the scenes. You can add, remove, and manipulate the pipelines to create your perfect documentation generator.

A good example is the modules section on the Wyam website. That page, and the detail pages for each module, are automatically generated from a single template file by examining the code analysis output that the Docs recipe already performs. Making use of that information to create an additional experience required very little additional code (just one extra pipeline in the configuration file and a single Razor template). I'd venture that heavily data-driven customization like this isn't this easy in any other generator.

A Piece Of Cake

I need to take a moment here and thank the Cake team for their support of this project. For the last several months, I've been working closely with them to convert their existing ASP.NET powered documentation site (which was already one of the best open source doc sites out there, at least in the .NET ecosystem) to a fully-static site powered by the new Wyam Docs recipe. It was a great use case requiring both built-in functionality and site-specific customization and helped mould this initial release of the Docs recipe. I couldn't have asked for better team mates. The result is a beautiful, fast, and robust documentation site. The source code for the new Cake site is available on GitHub and serves as a great example of Wyam Docs recipe deployment with some additional customization.

Go Forth And Build

If you're interested in taking a look, I'm happy to help. The Wyam website has detailed documentation, there's an active Gitter room, and I try to stay responsive with GitHub issues.