All plugins

Markdown, highlighting, search: each is a plugin you add, so your site carries what it uses and nothing else.

Every plugin is a NuGet package and one line in your pipeline:

Terminal

dotnet add package Nacara.Plugin.Markdown --prerelease

let site =
    Site.create "My library"
    |> Site.baseUrl "/"
    |> Markdown.register
    |> TextMate.register
    |> Theme.register theme
    |> Site.collection (Theme.docs theme "content")

Order does not matter, except that the last plugin to claim something wins, which is how one plugin replaces another.

Content

Package	What it gives you
`Nacara.Plugin.Markdown`	`.md` pages, front matter, directives, links checked at build time
`Nacara.Plugin.Highlight.TextMate`	Colour in code blocks, from TextMate grammars
`Nacara.Plugin.Highlight.TreeSitter`	The same, from tree-sitter grammars - a parser rather than patterns
`Nacara.Plugin.Literate`	`.fs` and `.fsx` files as pages, prose in comments
`Nacara.Plugin.LiveExample`	F# snippets a reader edits and runs, compiled in the browser
`Nacara.Plugin.Changelog`	`CHANGELOG.md` files published as pages

Publishing

Package	What it gives you
`Nacara.Plugin.Search`	A search box and modal, indexed by Pagefind
`Nacara.Plugin.Sitemap`	`sitemap.xml`, `robots.txt`, canonical links
`Nacara.Plugin.Versions`	Several versions side by side, with a switcher
`Nacara.Plugin.Deploy.GitHubPages`	The build published to the branch GitHub Pages serves
`Nacara.Plugin.Assets.LightningCss`	Smaller CSS, compiled for the browsers you name
`Nacara.Plugin.Assets.Esbuild`	One file out of JavaScript that imports its neighbours, minified
`Nacara.Plugin.Assets.Nuglify`	Smaller HTML, JavaScript and CSS
`Nacara.Plugin.FSharpApi`	Reference pages for an F# library, from the assemblies it ships

Checks

Package	What it gives you
`Nacara.Plugin.LinkValidator`	Every link the site published, checked
`Nacara.Plugin.Linter.Rumdl`	Every page's markdown, linted by rumdl

Themes

Package	What it gives you
`Nacara.Theme.Default`	The layout this site uses: navbar, sidebar, table of contents, dark mode

Its own pages cover customising it, the navbar, menus, and the components you can build your own layout from. Theming in the guide explains what a theme is here, whichever one you use.

Configuring a plugin

Every plugin has register for its defaults and registerWith for anything else. The options are a record, so your editor lists them and the compiler checks them:

|> Markdown.registerWith (fun options ->
    { options with
        GithubRepo = Some "MangelMaxime/Nacara"
        StrictLinks = false
    }
)

The pages above list every option, its default, and what it changes.

Writing your own

A plugin is a Registry -> Registry function in a package of your own: a few lines for a markdown extension, more for something that generates pages. Writing a plugin walks you through it.

Edit this page