Includes

Include syntax allows including contents of another file into the document. Content is included before the Markdown parsing as an preprocessor step. This allows including other Markdown files that will get parsed as they would've been part of the original document.

Include syntax also allows including C# code snippets from C# files (*.cs).

Include files

\#include::xref://src:DocsTool/Program.cs

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using Spectre.Console.Cli;
using Vertical.SpectreLogger;

var console = AnsiConsole.Create(new AnsiConsoleSettings());
console.Write(
    new FigletText("Tanka Docs")
        .LeftAligned()
        .Color(Color.Green)
        );

var services = new ServiceCollection();
services.AddSingleton<IAnsiConsole>(console);
services.AddLogging(logging =>
{
    logging.SetMinimumLevel(LogLevel.Debug);
    logging.AddSpectreConsole();
});

// steps 
services.AddDefaultPipeline();

var provider = services.BuildServiceProvider();
//todo: clean this
Infra.Initialize(provider.GetRequiredService<ILoggerFactory>());

var registrar = new TypeRegistrar(services);
var app = new CommandApp(registrar);
app.Configure(config =>
{
#if DEBUG
    config.PropagateExceptions();
    config.ValidateExamples();
#endif

    config.AddCommand<BuildSiteCommand>("build");
    config.AddCommand<DevCommand>("dev");
});

await app.RunAsync(args);

Include csharp code snippets or files

To use the Roslyn extension to find the given symbol you must target a .cs file with your include and provide a s(symbol) query string. Tanka Docs will load the given file using Roslyn and look for the symbol using the fully qualified symbol name. This allows including namespaces, classes, methods, properties.

Wrap includes into fenced code blocks to enable syntax highlighting.

Include ConfigurePreProcessors -method from RoslynExtension class.

\#include::xref://src:DocsTool/Extensions/Roslyn/RoslynExtension.cs?s=Tanka.DocsTool.Extensions.Roslyn.RoslynExtension.ConfigurePreProcessors

        public override Task ConfigurePreProcessors(Site site, Section section, PreProcessorPipelineBuilder builder)
        {
            builder.Add("**/*.md", new IncludeProcessor(xref => Resolver(site, section, xref)));
            return Task.CompletedTask;
        }