FSharp.Formatting

FSharp.Formatting is available on NuGet as a set of libraries for programmatic access to its core features. You can use it for:

• Markdown processing: Use the built-in F# Markdown parser to process and manipulate markdown documents.
• F# code formatting: Use the F# code formatter to analyze or format F# source files and extract information from them.

When using fsdocs, you can customize your documentation at six different levels of complexity:

1. No customization: Simply write content. This is the easiest to maintain.
2. Content customization: Add files like docs/index.md for a custom front page or docs/reference/Namespace.md to provide bespoke landing pages for specific namespaces (overriding generated content).
3. Styling Parameters: Use project file properties to set basic visual elements.
4. CSS: Override styles using a custom CSS file.
5. New Templates: Create custom HTML templates for the site structure.
6. Custom Site Generation: Use the FSharp.Formatting.ApiDocs API to generate a site using your own code.

When running fsdocs, the tool automatically searches for projects/solutions in the working directory. To be included in the API documentation, a project must meet these criteria:

• <OutputType> must be library.
• The project must be built (a binary must exist).
• <IsTestProject> must not be true.
• <GenerateDocumentationFile> must be true.

If you change these settings and the documentation doesn't update, try removing the .fsdocs/cache file.

To render a diagram, wrap your Mermaid syntax inside a <div> element that has the mermaid CSS class. The library will detect this class and render the text definition into a visual diagram.

<div class="mermaid">
graph LR
    A[Input docs] --> B[fsdocs build]
    B --> C[HTML output]
    B --> D[API reference]
</div>

It is recommended to install fsdocs-tool as a local dotnet tool to allow for independent version updates. First, create a dotnet tool manifest if one does not exist, then install the tool locally.

dotnet new tool-manifest
dotnet tool install --local fsdocs-tool

You can write Markdown documents containing embedded F# snippets and transform them into formatted HTML using the literate.fsx script provided by the FSharp.Formatting package. The document remains valid Markdown and supports standard features like unordered lists, bold, and emphasis.

# Example: Using Markdown Content

This file demonstrates how to write Markdown document with 
embedded F# snippets that can be transformed into nice HTML 
using the `literate.fsx` script from the [F# Formatting
package](http://fsprojects.github.io/FSharp.Formatting).

Use the watch command to generate documentation and start a local web server. This is ideal for development as it handles the root path correctly for local HTTP serving.

Run the command: dotnet fsdocs watch

By default, the server is available at http://localhost:8901.

To generate documentation for an F# project that includes project files, markdown, and script content (typically located in a docs directory), use the fsdocs command-line tool.

Follow these steps to install and run the tool:

1. Install the tool globally using dotnet tool install fsdocs-tool.
2. Build the documentation using dotnet fsdocs build.
3. Use dotnet fsdocs watch to monitor changes and rebuild automatically.

Use dotnet fsdocs build to generate static files for a production environment (like GitHub Pages).

Local Preview Tip: If <PackageProjectUrl> is not set, opening the output files directly in a browser via file:// will result in broken links. To preview the build locally without a web server, pass a relative root:

dotnet fsdocs build --parameters root ./