Configuration

The starlight-fsharp-literate plugin can be configured in astro.config.mjs configuration file.

It supports two modes: inline and mirror. The default is inline.

export default defineConfig({
    integrations: [
        fsharpLiterate({
            // Configuration options go here
        }),
        starlight({
            // ... starlight options
        }),
    ],
});

Modes

inline (default)

Type: { mode: "inline", base?: string }

Default: { mode: "inline", base: "src/content/docs" }

Source files live alongside their generated output inside the same directory.

• Directorysrc

  • astro.config.mjs
  • Directorycontent/docs/

    • guide.source.fsx you edit this
    • guide.mdx generated, gitignored

inline mode is the default and is used when no options are provided.

fsharpLiterate()
// equivalent to:
fsharpLiterate({
    mode: "inline",
    base: "src/content/docs"
})

The object contains the following properties:

• mode: "inline" (required) — selects inline mode

• base: string (optional) — directory scanned recursively for source files

  Default is "src/content/docs"

mirror

Type: { mode: "mirror", sourceDir?: string, outputDir?: string, sourceExtensions?: string[] }

Default: { mode: "mirror", sourceDir: "src/content/fsharp-literate", outputDir: "src/content/docs" }

Source files live in a dedicated directory that mirrors the output directory structure.

• Directorysrc

  • astro.config.mjs
  • Directorycontent/

    • Directoryfsharp-literate/

      • guide.fsx you edit this
    • Directorydocs/

      • guide.mdx generated, gitignored

fsharpLiterate({ mode: "mirror" })
// equivalent to:
fsharpLiterate({
    mode: "mirror",
    sourceDir: "src/content/fsharp-literate",
    outputDir: "src/content/docs",
    sourceExtensions: [".fsx", ".fs"]
})

The object contains the following properties:

• mode: "mirror" (required) — selects mirror mode

• sourceDir: string (optional) — directory scanned recursively for source files

  Default is "src/content/fsharp-literate"

• outputDir: string (optional) — directory where generated .mdx files are written, preserving the relative structure of sourceDir

  Default is "src/content/docs"

• sourceExtensions: string[] (optional) — file extensions used to identify source files

  Default is [".fsx", ".fs"]

VSCode Settings

VSCode supports file nesting in the explorer, you can configure it to nest generated .mdx files under their source files.

Add the following to your workspace settings:

{
    "explorer.fileNesting.enabled": true,
    "explorer.fileNesting.expand": false,
    "explorer.fileNesting.patterns": {
        "*.source.fs": "${capture}.mdx",
    }
}