BlakePlugin.DocsRenderer 0.0.1-preview2

BlakePlugin.DocsRenderer

A plugin for Blake that adds scrollspy, TOC navigation, and beautiful code blocks to your documentation.

Features

• In-page navigation with scrollspy
• Document sectioning
• Custom Prism code rendering
• Customizable styles
• Includes default Bootstrap styles (works with the default Blazor template)
• Default Razor components for navigation and sectioning

How it works

The plugin adds a Markdig renderer to the Markdown pipeline to process documentation pages more intelligently (there's nothing stopping you adding this to your blog though, too!). It uses headings to automatically split the content into sections and generates a table of contents. The scrollspy functionality highlights the current section in the navigation as the user scrolls through the page.

The plugin adds a custom Prism code renderer to the pipeline that enhances the default behavior by adding custom line numbering, line diffing, and other features. The included styles and JavaScript add visual and functional enhancements to code blocks.

Installation

1. Add the package:

   dotnet add package BlakePlugin.DocsRenderer
   

2. Import the necessary styles and scripts in your index.html, and initialise the DocsRenderer:

   
   <link rel="stylesheet" href="_content/BlakePlugin.DocsRenderer/lib/docsrenderer.css">
   
   
   <script src="_content/BlakePlugin.DocsRenderer/lib/docsrenderer.js"></script>    
   <script>initDocsRenderer();</script> 
   

Usage

Razor Setup

Once the plugin is installed, you can use the built-in Razor components to render both the site-wide and in-page table of contents.

Make sure to import the relevant namespaces at the top of your .razor file:

@using BlakePlugin.DocsRenderer // Required for Section, note this is automatically added to generated pages
@using BlakePlugin.DocsRenderer.Components // Required for SiteToc and PageToc components
@using BlakePlugin.DocsRenderer.Utils // Required for TocNode and TocUtils

Adding navigation components

You can now use the SiteToc and PageToc components in your Razor pages or components, or template.razor files:

<SiteToc Pages="@contentIndex" />



<PageToc Sections="@_sections" />

Generating TOC and Section Data

In your @code block, you’ll typically initialise the table of contents like this:

@code {
    private List<TocNode> contentIndex = TocUtils.BuildSiteTocNodes(GeneratedContentIndex.GetPages());

    // This list of sections is automatically generated by the plugin
    private List<Section> _sections = [

        new Section { Text = "Introduction", Id = "introduction", Children = [ // ...] },
        new Section { Text = "Getting Started", Id = "getting-started", Children = [] /*Empty in this case*/ },
        // ...
    ];
}

The _sections list is automatically injected by the plugin into the generated Razor page at build time, so you don't need to maintain it manually unless you’re testing or debugging. (Note the comments were added just for this example, they are not present in the actual code.)

Customisation

While the behaviour of the plugin is mostly fixed, you can use the generated data to drive your own components. The included components are trivial; you can copy the code and modify it to suit your needs (e.g. add your own styles or additional functionality).