Command line

To use F# Formatting tools via the command line, you can use the fsdocs dotnet tool.

dotnet tool install fsdocs-tool
dotnet fsdocs [command] [options]

The build command

This command processes a docs directory and generates API docs for projects in the solution according to the rules of API doc generation. The input accepted is described in content.

fsdocs build

The command line options accepted are:

The following command line options are also accepted but it is instead recommended you use settings in your .fsproj project files:

Project file settings

Many fsdocs behaviours can be controlled via MSBuild properties in your .fsproj (or Directory.Build.props) file.

The command will report on any .fsproj files that it finds, telling you if it decides to skip a particular file and why.

For example, a project will be skipped if:

• The project name contains ".Tests" or "test" (because it looks like a test project)

• The project does not contain

  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  

• The project OutputType is not Library. To include an executable project, add this to the project file:

  <FsDocsAllowExecutableProject>true</FsDocsAllowExecutableProject>
  

The watch command

This command does the same as fsdocs build but in "watch" mode, waiting for changes. Only the files in the input directory (e.g. docs) are watched. A browser will be launched automatically (unless --nolaunch is specified).

You will need to ensure that the input directory exists, and contains at least index.md, otherwise the browser will report an error (e.g. "Problem loading...", "Connection was reset").

fsdocs watch

Restarting may be necesssary on changes to project files. The same parameters are accepted, plus these:

Searchable docs

When using the command-line tool a Fuse search index is automatically generated in index.json. A search box is included in the default template via an HTML Dialog element.
To add search to your own _template.html:

• include an HTML element with id search-btn
• include a dialog element
• include fsdocs-search.js script

<button id="search-btn">Open search dialog</button>
<dialog>
    <input type="search" placeholder="Search docs" />
    <div class="results">
        <ul></ul>
        <p class="empty">Type something to start searching.</p>
    </div>
</dialog>
<script type="module" src="{`{root}}content/fsdocs-search.js"></script>

Embedding Images

Downloading Remote Images (--saveimages)

The --saveimages flag controls whether images referenced in your docs are downloaded and saved locally alongside the generated output. This is primarily useful for non-HTML output formats such as LaTeX (PDF) and Jupyter Notebook (.ipynb), which cannot reference remote URLs at display time.

Example:

fsdocs build --saveimages some

Embedding Images Generated by Scripts

When using --eval to evaluate literate F# scripts, you can embed images produced by code (e.g. charts, plots) directly into the HTML output.

Option 1: Inline Base64 image using include-it-raw

Write a helper that reads an image file and returns an HTML <img> tag with the image data embedded as a Base64 string. Then use (*** include-it-raw ***) to inject the raw HTML into the output:

let inlinePng (fileName: string) =
    let bytes = System.IO.File.ReadAllBytes(fileName)
    let b64 = System.Convert.ToBase64String(bytes)
    sprintf """<img src="data:image/png;base64,%s" />""" b64

// Generate the image in your script, then embed it:
// myChart.SavePng("chart.png")
// (*** hide ***)
// inlinePng "chart.png"
// (*** include-it-raw ***)

The (*** hide ***) command suppresses the source code of the expression, so only the rendered image appears in the output.

Option 2: Custom HTML printer via fsi.AddHtmlPrinter

If your charting library produces values of a known type, you can register a custom HTML printer so that values of that type are automatically rendered as images whenever they appear via (*** include-it ***). See Embedding Script Output for details.