Documentation Middleware

This package allows to capture GET requests and if the route matches with an existing markdown or HTML file, renders it inside a layout.

Usage

It is useful to use it along with StaticFiles in order to allow to also render images and other files.

Example:

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMvc();
    }

    public void Configure(IApplicationBuilder app, IApplicationEnvironment appEnv)
    {
        app.UseMvc();

        app.UseStaticFiles();

        app.UseDocumentation(new DocumentationOptions()
        {
            DefaultFileName = "index",
            RequestPath = "/docs",
            NotFoundHtmlPath = "NotFound.html",
            LayoutFilePath = "Layout.html"
        });
    }
}

Versioning and publishing

project.json:

{
  "version": "0.1.0-beta7-*",

For a version release, version property in project.json should NOT contain -* because our appveyor.yml configuration file, uses it to inject build number. See https://ci.appveyor.com/project/andresmoschini/makingsense-aspnet-documentation. It requires to update both project.json and appvoyer.yml`.

Examples: 1.0.5-beta7 should be considered the definitive 1.0.5 version for beta7 framework, 1.0.5-beta7-237 is a pre-release of 1.0.5-beta7. If the library is upgraded for framework beta8, the new version will be 1.0.5-beta8, when it is upgraded to final DNX version, the new version will be something like 1.0.5 and pre-releases versions something like 1.0.5-785.

Before merge any PR, version property in project.json should be updated using Semantic Versioning.

I wish to use GitVersion but it seems that it is not enough mature for DNX projects.

Maybe we could upload only definitive versions to NuGet Gallery and all versions including definitive and pre-release ones to MyGet.

Multilanguage support

Too add multilanguage support, append two digits language code to the file name before the extension.

Set DefaultLanguage property to add a language fallback for URLs with no language code specified.

Example

    app.UseDocumentation(new DocumentationOptions()
    {
        RequestPath = "/docs",
        DefaultLanguage = "en",
        ...

    /docs/es/filename   =>  filename.es    (and if not exist)  =>  filename
    /docs/en/filename   =>  filename.en    (and if not exist)  =>  filename
    /docs/filename      =>  filename.en    (and if not exist)  =>  filename

Layout transalation

To enable layout and not found files translation, set SupportedLanguages property along with LayoutFilePath and NotFoundHtmlPath.

    app.UseDocumentation(new DocumentationOptions()
    {
        NotFoundHtmlPath = "NotFound.html",
        LayoutFilePath = "Layout.html",
        SupportedLanguages = new string[] { "en", "es" },
        ...