the cloud way

ElCamino.DocFx.WebAppRefresh

DocFx build middleware that allows you to setup a .net core web app project and adds a file watcher to your content files. When you change a content file, such as markdown, css, etc, the middleware automatically starts a docFx build in the background regenerating the target html files. Sample .net core web application

This library should be configured for local development only as shown below!

1. Create a new .net core web application 'Empty' project

dotnet new web

or

Use Visual Studio new project, web application, Empty.

2. Create a dotnet tool manifest file for docFx

dotnet new tool-manifest 

3. Add the docFx tool

dotnet tool install docfx 

4. Create a new docFx project in the root of the web application (if you have not already done so)

docfx init 

5. Rename the _site folder to wwwroot in the docfx.json. (if needed)
6. Edit the .gitignore file, remove _site, add wwwroot and log.txt

wwwroot
log.txt

7. Edit the docfx.json, rename _site and replace with wwwroot

{
    "dest": "wwwroot"
}

8. Edit the project file to add build actions for docFx

    <Target Name="RestoreDocFxTool" BeforeTargets="CreateDocFxJson">
		<Exec Command="dotnet tool restore" WorkingDirectory="$(ProjectDir)" />
	</Target>
	<Target Name="CreateDocFxJson" AfterTargets="Build">
		<Exec Command="dotnet docfx docfx.json" WorkingDirectory="$(ProjectDir)" />
	</Target>
	

7. Use the nuget package manager to install ElCamino.DocFx.WebAppRefresh

dotnet add package ElCamino.DocFx.WebAppRefresh 

8. Edit the Startup.cs

public class Startup
{
    ...
    // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
            // only use in development, not for production
            app.UseDocFxBuildRefresh(env.ContentRootPath, env.WebRootPath);
        }
        app.UseDefaultFiles();

        app.UseStaticFiles();
    }
...

9. Debug the web application. Change a content file (markdown, css, etc) and watch the debug output for the docFx build output and refresh the page to see your changes.