DocFX
DocFX is a powerful documentation generator and static website builder. It is commonly used to host documentation for teams and projects, making it the perfect platform to showcase your team's road map. Of course, needing to manually render your road map into Markdown and then update the file isn't the best workflow, so we've built a DocFX plugin which will render your roadmap.yml
file into a gorgeous documentation page without any extra work on your part.
Usage
Prerequisites
You'll need DocFX installed on your machine and a prepared project, the best way to do this is by following their Getting Started Guide.
Installation
Using NuGet
The simplest way to install the package is using NuGet.
# NOTE: You might need to accept a warning prompt to let this access nuget.org
Install-Package -ExcludeVersion -Destination . -SkipDependencies -Name DocFX.Plugins.Roadmap -Force
# Make sure that you have the NuGet.exe on your path (https://www.nuget.org/downloads)
nuget install DocFX.Plugins.Roadmap -ExcludeVersion -OutputDirectory .
Manual Installation
If you don't have NuGet installed, or would prefer to do things the hard way, then you can manually extract the package by downloading it directly from NuGet.org. To do so, follow these steps.
- Head to the DocFX.Plugins.Roadmap package on nuget.org.
- Click the
Download Package
link on the right hand side, under the About heading. - Rename the file and add a
.zip
extension to it, it should now look something likedocfx.plugins.roadmap.1.0.10.nupkg.zip
. - Open your new zip file and extract the
content
directory into aDocFX.Plugins.Roadmap/content
directory inside your project.
WARNING
If you are able to, NuGet is a much simpler way to install the package and is less prone to failure.
Configuring DocFX
Once you have installed the plugin, you will need to configure DocFX to use it. This is done by adding the plugin's content
directory to your template
list. This will cause DocFX to load the plugin and apply it to any roadmap.yml
files in your project.
// docfx.json
{
"metadata": [],
"build": {
"content": [{ ... }],
"resource": [{ ... }],
"dest": "_site",
"template": ["default", "DocFX.Plugins.Roadmap/content"]
}
}
Creating a Road map
Once you have installed the plugin, you can render a road map by placing a roadmap.yml
file anywhere within your configured DocFX content directories. The renderer will convert this into a roadmap.html
file and you can list in either your toc.yml
files or link to it from other pages.
Output
The renderer generates an HTML file which will leverage your existing DocFX theme and which looks something like the following when rendered. The content generated by the renderer is plain HTML+CSS, so it should be widely compatible and doesn't introduce any external dependencies.