OPS Includes

[!INCLUDE] and [!code-lang] directives — fetched + spliced into the AST.

OPS Includes#

Markdown INCLUDE#

The directive [!INCLUDE [label](../_includes/install.md)] fetches the referenced file (via the same source as the parent page), parses it through the full markdown pipeline, and splices the resulting blocks into the current AST. Containers / code / xref inside the include all keep working.

Result:

Install (shared snippet)#

This block is authored once in _includes/install.md and pulled in via [!INCLUDE] from any page that needs install instructions.

bash

# Mac / Linux
curl -fsSL https://example.com/install.sh | bash

# Windows (PowerShell)
iwr https://example.com/install.ps1 | iex

The included markdown is parsed through the same pipeline as the parent, so containers, code fences, and other directives nest correctly.

Back to the main page after the include.

Code include — full file#

[!code-csharp[label](../_snippets/sample.cs)] embeds the whole file:

sample.cscsharp

using System;
using System.Collections.Generic;
using System.Linq;

namespace Vellum.Demo;

// <region name="repos">
public record RepoConfig(
    string Slug,
    string Source,
    string DocsRoot,
    string DisplayName,
    string? Owner = null,
    string? Repo = null,
    string? Branch = null);
// </region>

public static class Sources
{
    // <region name="resolve">
    public static async Task<string?> ResolveAsync(RepoConfig repo, string path)
    {
        return repo.Source switch
        {
            "github" => await FetchGitHubAsync(repo.Owner!, repo.Repo!, repo.Branch!, path),
            "local"  => await FetchLocalAsync(repo.Slug, path),
            _        => throw new ArgumentException($"unknown source: {repo.Source}"),
        };
    }
    // </region>

    private static Task<string?> FetchGitHubAsync(string owner, string repo, string branch, string path) =>
        Task.FromResult<string?>(null);

    private static Task<string?> FetchLocalAsync(string slug, string path) =>
        Task.FromResult<string?>(null);
}

public static class Program
{
    public static void Main()
    {
        var repos = new List<RepoConfig>
        {
            new("prism",    "github", "docs", "Prism",    "siiway", "prism",   "main"),
            new("glint",    "github", "docs", "Glint",    "siiway", "glint",   "main"),
            new("handbook", "local",  "",     "Handbook"),
        };

        foreach (var r in repos.OrderBy(r => r.Slug))
        {
            Console.WriteLine($"{r.Slug,-10} {r.Source,-6} {r.DisplayName}");
        }
    }
}

Code include — line range#

[!code-csharp[label](../_snippets/sample.cs?range=12-21)] slices to lines 12–21 (the RepoConfig record):

sample.cscsharp

    string DisplayName,
    string? Owner = null,
    string? Repo = null,
    string? Branch = null);
// </region>

public static class Sources
{
    // <region name="resolve">
    public static async Task<string?> ResolveAsync(RepoConfig repo, string path)

Code include — highlighted lines#

?range=25-35&highlight=3 keeps the slice and highlights the third line within it:

sample.cscsharp

        "github" => await FetchGitHubAsync(repo.Owner!, repo.Repo!, repo.Branch!, path),
        "local"  => await FetchLocalAsync(repo.Slug, path),
        _        => throw new ArgumentException($"unknown source: {repo.Source}"),
    };
}
// </region>

private static Task<string?> FetchGitHubAsync(string owner, string repo, string branch, string path) =>
    Task.FromResult<string?>(null);

private static Task<string?> FetchLocalAsync(string slug, string path) =>

Code include — by region#

DocFX-style #region <name> / #endregion markers carve out named ranges. [!code-csharp[label](../_snippets/sample.cs#repos)] returns the lines between #region repos and #endregion:

sample.cscsharp

public record RepoConfig(
    string Slug,
    string Source,
    string DocsRoot,
    string DisplayName,
    string? Owner = null,
    string? Repo = null,
    string? Branch = null);

And by query parameter (?region=resolve):

sample.cscsharp

public static async Task<string?> ResolveAsync(RepoConfig repo, string path)
{
    return repo.Source switch
    {
        "github" => await FetchGitHubAsync(repo.Owner!, repo.Repo!, repo.Branch!, path),
        "local"  => await FetchLocalAsync(repo.Slug, path),
        _        => throw new ArgumentException($"unknown source: {repo.Source}"),
    };
}

Code include — different language#

Python snippet:

fizzbuzz.pypython

def fizzbuzz(n: int) -> str:
    """Return the FizzBuzz string for n."""
    if n % 15 == 0:
        return "FizzBuzz"
    if n % 3 == 0:
        return "Fizz"
    if n % 5 == 0:
        return "Buzz"
    return str(n)


def main() -> None:
    for i in range(1, 16):
        print(fizzbuzz(i))


if __name__ == "__main__":
    main()

Code include — start/end#

?start=4&end=12:

fizzbuzz.pypython

        return "FizzBuzz"
    if n % 3 == 0:
        return "Fizz"
    if n % 5 == 0:
        return "Buzz"
    return str(n)


def main() -> None: