Build lifecycle & hook order

This page is the visual reference for where things hook into a Netdocs build. If you are writing a plugin or a theme override and you are not sure when your code runs — or where in the pipeline you should hook in — start here.

Everything below is driven by BuildEngine.BuildAsync, which orchestrates one build from config to emitted HTML.

The pipeline at a glance

flowchart TD
    A[Load appsettings.json to SiteConfig] --> B[Load external plugins
plugins/*.dll]
    B --> C[Build plugin host
IPlugin.Configure on every plugin]
    C --> D[Discover docs/**
ContentDiscovery]
    D --> E{INavigationFilter
ShouldInclude}
    E -->|kept| F[IBuildHook.OnBuildStartAsync]
    F --> G[IContentGenerator.GenerateAsync
virtual pages: blog, tags, archives]
    G --> H[IMarkdownPreprocessor.ProcessAsync
ordered by Order — snippets, abbr, macros]
    H --> I[Parse + render Markdown
Markdig pipeline + IMarkdigContributor.Extend
parallel, render-cache aware]
    I --> J[Resolve navigation
NavigationBuilder]
    J --> K[Template render
Scriban + theme, parallel to HTML]
    K --> L[Emit 404.html]
    L --> M[IBuildHook.OnPageRenderedAsync
per page]
    M --> N[Copy assets
theme + docs static + plugin-registered]
    N --> O[IBuildHook.OnBuildCompleteAsync
search index, rss, tags.json]
    O --> P[Emit sitemap.xml]
    P --> Q[Prune stale output files]

    classDef hook fill:#e8f0fe,stroke:#3f51b5,color:#1a237e;
    class E,F,G,H,I,M,O hook;

The blue nodes are the extension points a plugin can implement. Everything else is engine-owned.

Ordered stages

Preprocessor ordering

Preprocessors are sorted by their Order property (ascending). The built-ins use:

Pick an Order relative to these when you need your preprocessor to run before or after a built-in.

Overriding order from config

You don't need to recompile a plugin to change where it runs: set an order on its plugins entry to override its natural Order. Lower runs earlier; ties keep config order. For example, to run macros before table-reader:

{ "name": "macros", "order": 15 }

Other hook types (Markdig contributors, content generators, build hooks, navigation filters) run in the order their plugins are listed in plugins, so reordering that list is all that's needed for them.

Template render order

Stage 11 renders each page with Scriban. The theme's main.html is the root layout; it pulls in partials in roughly this order:

flowchart TD
    M[main.html] --> H[partials/header.html]
    M --> N[partials/nav.html]
    M --> T[partials/toc.html]
    M --> C[page.content — rendered Markdown]
    M --> PM[partials/post-meta.html
blog posts]
    M --> BN[partials/blog-nav.html
blog views]
    M --> F[partials/footer.html]
    M --> S[partials/search.html]
    M --> HL[partials/highlight.html]
    M --> ME[partials/mermaid.html]
    M --> TB[partials/tabs.html]

To override any of these, point theme.custom_dir at a folder of Scriban templates that mirror the theme layout. (Material's Jinja2 overrides are detected and ignored.) See Theme reference.

Choosing where to hook

See the Events & callbacks reference for the exact method signatures and examples.