FSharp.Formatting

https://fsprojects.github.io/FSharp.Formatting/
Admin
FSharp.Formatting is a set of libraries and tools for processing F# script files, markdown, and...
Tokens:62,360
Snippets:512
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Fsdocs-tool Locally

Source: https://fsprojects.github.io/FSharp.Formatting/zero-to-hero

Installs the `fsdocs-tool` as a local dependency for the project. This allows for controlled updates to the tool version.

```bash
dotnet tool install --local fsdocs-tool
```

--------------------------------

### Load Project Binary in FsDocs Script (F#)

Source: https://fsprojects.github.io/FSharp.Formatting/zero-to-hero

Demonstrates how to load a project's binary into an FsDocs script for creating documentation examples. It uses '#r' to reference the DLL and 'open' to access the project's namespace.

```fsharp
#r "../src/Project1/bin/Debug/net6.0/Project1.dll"

open Project1

// Actual consumption of your project!
let result = SomeType.SomeMethod("foo")

```

--------------------------------

### View Fsdocs Commands

Source: https://fsprojects.github.io/FSharp.Formatting/zero-to-hero

Displays the available commands and options for the `fsdocs` tool, useful for understanding its capabilities after installation.

```bash
dotnet fsdocs --help
```

--------------------------------

### GitHub Actions CI Workflow for FsDocs Build

Source: https://fsprojects.github.io/FSharp.Formatting/zero-to-hero

A sample GitHub Actions workflow file that triggers on pull requests. It sets up .NET, restores tools, builds the solution, and then runs the FsDocs build command.

```yaml
name: CI

on: [pull_request]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3
    - name: Setup .NET Core
      uses: actions/setup-dotnet@v3
    - name: Restore tools
      run: dotnet tool restore
    - name: Build
      run: dotnet build YourSolution.sln
    - name: Documentation
      run: dotnet fsdocs build


```

--------------------------------

### GitHub Actions Workflow for Deploying Documentation

Source: https://fsprojects.github.io/FSharp.Formatting/zero-to-hero

This YAML workflow automates the deployment of documentation to GitHub Pages. It checks out code, sets up .NET, restores tools, builds the project, generates documentation using 'dotnet fsdocs build', and uploads the output as an artifact for deployment.

```yaml
name: Docs

# Trigger this Action when new code is pushed to the main branch
on:
  push:
    branches:
      - main

# We need some permissions to publish to Github Pages
permissions:
  contents: write
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      # Checkout the source code
      - uses: actions/checkout@v4
      # Setup dotnet, please use a global.json to ensure the right SDK is used!
      - name: Setup .NET
        uses: actions/setup-dotnet@v3
      # Restore the local tools
      - name: Restore tools
        run: dotnet tool restore
      # Build the code for the API documentation
      - name: Build code
        run: dotnet build -c Release YourSolution.sln
      # Generate the documentation files
      - name: Generate the documentation'
        run: dotnet fsdocs build --properties Configuration=Release
      # Upload the static files
      - name: Upload documentation
        uses: actions/upload-pages-artifact@v2
        with:
          path: ./output
  
  # GitHub Actions recommends deploying in a separate job.
  deploy:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2
```

--------------------------------

### Install and Run fsdocs Tool

Source: https://fsprojects.github.io/FSharp.Formatting/commandline

Instructions for installing the fsdocs dotnet tool and the basic command structure for running it. This is the entry point for using the command-line interface.

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

--------------------------------

### Dependabot Configuration for NuGet and GitHub Actions Updates

Source: https://fsprojects.github.io/FSharp.Formatting/zero-to-hero

Configuration file for Dependabot to automatically check for and create pull requests for updates to NuGet packages and GitHub Actions. It specifies the update interval for each package ecosystem.

```yaml
version: 2
updates:
  # Update to newer version of GitHub Actions
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"

  # Update to newer NuGet dependencies
  - package-ecosystem: "nuget"
    directory: "/"
    schedule:
      interval: "daily"


```

--------------------------------

### Fsdocs Project Configuration for API Documentation

Source: https://fsprojects.github.io/FSharp.Formatting/zero-to-hero

Details the requirements for FSharp projects to be included in API documentation generation by `fsdocs`. This includes setting the output type to library, ensuring a build is performed, excluding test projects, and enabling documentation file generation.

```xml
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>library</OutputType>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <IsTestProject>false</IsTestProject>
  </PropertyGroup>
</Project>
```

--------------------------------

### fsdocs-tool Local Installation and File Operations

Source: https://fsprojects.github.io/FSharp.Formatting/upgrade

Demonstrates installing the fsdocs-tool locally, managing NuGet tool manifests, and performing file system operations for project restructuring.

```bash
dotnet tool install fsdocs-tool --local
git add dotnet-tools.json   
git rm -fr docs/tools
git mv docs/input/* docs
git mv docs/files/* docs
```

--------------------------------

### F# Programmatic API Docs Generation Setup

Source: https://fsprojects.github.io/FSharp.Formatting/apidocs

Demonstrates the setup required to programmatically generate library documentation using FSharp.Formatting.ApiDocs. It includes loading the necessary DLL and opening relevant namespaces.

```fsharp
#r "FSharp.Formatting.ApiDocs.dll"

open FSharp.Formatting.ApiDocs
open System.IO
```

--------------------------------

### Configure Project Properties with Directory.Build.props

Source: https://fsprojects.github.io/FSharp.Formatting/zero-to-hero

This XML snippet shows how to configure MSBuild properties like RepositoryUrl, FsDocsLicenseLink, FsDocsReleaseNotesLink, and PackageProjectUrl in a Directory.Build.props file. These properties are crucial for generating correct links in documentation and for the build process.

```xml
<Project>
    <PropertyGroup>
        <RepositoryUrl>https://github.com/fsprojects/FSharp.AWS.DynamoDB</RepositoryUrl>
        <FsDocsLicenseLink>https://github.com/fsprojects/FSharp.AWS.DynamoDB/blob/master/License.md</FsDocsLicenseLink>
        <FsDocsReleaseNotesLink>https://github.com/fsprojects/FSharp.AWS.DynamoDB/blob/master/RELEASE_NOTES.md</FsDocsReleaseNotesLink>
        <PackageProjectUrl>https://fsprojects.github.io/FSharp.AWS.DynamoDB</PackageProjectUrl>
    </PropertyGroup>
</Project>
```

--------------------------------

### Access ApiDocComment Examples

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidoccomment

Retrieves a list of example sections from an ApiDocComment object. The examples are returned as a list of ApiDocHtml, representing the formatted HTML content of each example.

```F#
this.Examples
```

--------------------------------

### Install fsdocs-tool

Source: https://fsprojects.github.io/FSharp.Formatting/upgrade

Installs the fsdocs-tool globally using the .NET CLI. This is the first step in upgrading to fsdocs.

```bash
dotnet new tool
dotnet tool install fsdocs-tool
```

--------------------------------

### Install and Build F# Documentation with fsdocs-tool

Source: https://fsprojects.github.io/FSharp.Formatting/index

This snippet shows how to install the fsdocs-tool using the .NET CLI and then build or watch for changes in your F# project's documentation.

```bash
dotnet tool install fsdocs-tool
dotnet fsdocs build 
dotnet fsdocs watch
```

--------------------------------

### Watch for Documentation Changes

Source: https://fsprojects.github.io/FSharp.Formatting/upgrade

Starts a local development server that watches for changes in the documentation files and rebuilds the site automatically.

```bash
dotnet fsdocs watch
```

--------------------------------

### F# Formatting API Cross-Reference Examples

Source: https://fsprojects.github.io/FSharp.Formatting/content

Demonstrates how to use the 'cref:' syntax within Markdown to create cross-references to F# and .NET API documentation. These examples show how different signatures resolve to specific documentation links.

```markdown
``cref:T:FSharp.Formatting.Markdown.MarkdownParagraph``
```

```markdown
``cref:T:System.Console``
```

```markdown
``cref:M:System.Console.WriteLine``
```

```markdown
``cref:M:System.Console.WriteLine(System.String)``
```

```markdown
```cref:T:FSharp.Control.FSharpAsync`1```
```

--------------------------------

### FSharp.Formatting CLI Usage

Source: https://fsprojects.github.io/FSharp.Formatting/commandline

Installs and runs the fsdocs dotnet tool for generating documentation.

```APIDOC
## Install and Use fsdocs CLI

### Description
Installs the fsdocs dotnet tool and provides basic usage instructions.

### Method
CLI Command

### Endpoint
N/A

### Parameters
None

### Request Example
```bash
dotnet tool install fsdocs-tool
dotnet fsdocs [command] [options]
```

### Response
N/A
```

--------------------------------

### Moving F# Code Definitions with Include/Define

Source: https://fsprojects.github.io/FSharp.Formatting/sidebyside/sidescript

Illustrates using 'include' and 'define' commands in F# Formatting to manage code execution order, allowing code to be explained before its definition appears in the script.

```fsharp
let sample = laterFunction () |> printfn "Got: %s"

```

```fsharp
let laterFunction () = "Not very difficult, is it?"

```

--------------------------------

### Markdown Link Translation Example

Source: https://fsprojects.github.io/FSharp.Formatting/content

Shows how a markdown link to a local file (e.g., 'some-file.md') is automatically translated to a link to its corresponding HTML output file ('some-file.html') during the documentation build process.

```markdown
[Some Text](some-file.md)

```

--------------------------------

### Basic F# Function: Factorial

Source: https://fsprojects.github.io/FSharp.Formatting/sidebyside/sidescript

Defines a recursive factorial function in F#. This is a common example demonstrating basic F# syntax and recursion.

```fsharp
/// The Hello World of functional languages!
let rec factorial x =
    if x = 0 then 1 else x * (factorial (x - 1))

let f10 = factorial 10

```

--------------------------------

### Programmatic API Documentation Generation

Source: https://fsprojects.github.io/FSharp.Formatting/apidocs

Provides instructions and code examples for generating API documentation programmatically using the `ApiDocs` type from the `FSharp.Formatting.ApiDocs` library. This includes loading assemblies and using methods like `GenerateHtml`.

```APIDOC
## Building library documentation programmatically

### Description
This section explains how to programmatically generate library documentation using the `ApiDocs` functionality. It covers loading assemblies, specifying input files, and configuring output options for HTML generation.

### Method
N/A (Library Functionality)

### Endpoint
N/A

### Parameters
None

### Request Example
```fsharp
#r "FSharp.Formatting.ApiDocs.dll"

open FSharp.Formatting.ApiDocs
open System.IO

let file = Path.Combine(root, "bin/YourLibrary.dll")

let input = ApiDocInput.FromFile(file)

ApiDocs.GenerateHtml(
    [ input ],
    output = Path.Combine(root, "output"),
    collectionName = "YourLibrary",
    template = Path.Combine(root, "templates", "template.html"),
    substitutions = []
)
```

### Response
None

#### Success Response (N/A)
N/A

#### Response Example
None
```

--------------------------------

### F# Script Front Matter Example

Source: https://fsprojects.github.io/FSharp.Formatting/content

Illustrates the front matter format specific to F# scripts, using a similar YAML structure enclosed in F# comment syntax for metadata.

```fsharp
(*
---
title: A Literate Script
category: Examples
categoryindex: 2
index: 1
description: Some description
keywords: tag1, tag2, tag3
---
*)

```

--------------------------------

### F# API Docs Generation using GenerateHtml

Source: https://fsprojects.github.io/FSharp.Formatting/apidocs

Provides an example of using the `ApiDocs.GenerateHtml` method to create HTML documentation from a compiled F# assembly. It specifies input assembly, output directory, collection name, and template.

```fsharp
let file = Path.Combine(root, "bin/YourLibrary.dll")

let input = ApiDocInput.FromFile(file)

ApiDocs.GenerateHtml(
    [ input ],
    output = Path.Combine(root, "output"),
    collectionName = "YourLibrary",
    template = Path.Combine(root, "templates", "template.html"),
    substitutions = []
)
```

--------------------------------

### Set FsDocs Styling Parameters in Project File

Source: https://fsprojects.github.io/FSharp.Formatting/styling

This example demonstrates how to configure various FsDocs styling and generation parameters within a .NET project file (e.g., .fsproj). These parameters control aspects like logo, favicon, license links, and warning behavior, affecting the final generated documentation site.

```xml
<PropertyGroup>
    <!-- Example ultra-simple styling and generation settings for FsDocs default template-->
    <PackageLicenseUrl>https://github.com/foo/bar/blob/master/License.txt</PackageLicenseUrl>
    <PackageProjectUrl>https://foo.github.io/bar/</PackageProjectUrl>
    <RepositoryUrl>https://github.com/foo/bar/</RepositoryUrl>
    <FsDocsLogoLink>https://fsharp.org</FsDocsLogoLink>
    <FsDocsLogoSource>img/logo.png</FsDocsLogoSource>
    <FsDocsFaviconSource>img/favicon.ico</FsDocsFaviconSource>
    <FsDocsLicenseLink>https://github.com/foo/bar/blob/master/License.txt</FsDocsLicenseLink>
    <FsDocsReleaseNotesLink>https://github.com/foo/bar/blob/master/release-notes.md</FsDocsReleaseNotesLink>
    <FsDocsWarnOnMissingDocs>true</FsDocsWarnOnMissingDocs>
    <FsDocsTheme>default</FsDocsTheme>
</PropertyGroup>
```

--------------------------------

### F# Code Snippet Example

Source: https://fsprojects.github.io/FSharp.Formatting/sidebyside/sidemarkdown

Demonstrates embedding a standard F# code snippet within Markdown. This code is processed and formatted by FSharp.Formatting.

```fsharp
/// The Hello World of functional languages!\
let rec factorial x = 
  if x = 0 then 1 
  else x * (factorial (x - 1))

let f10 = factorial 10

```

--------------------------------

### Markdown Front Matter Example

Source: https://fsprojects.github.io/FSharp.Formatting/content

Demonstrates the YAML front matter format used in markdown files to define metadata for documentation generation, including title, category, and keywords.

```markdown
---
title: Some Title
category: Some Category
categoryindex: 2
index: 3
description: Some description
keywords: tag1, tag2, tag3
---

```

--------------------------------

### F# Function with XML Docs

Source: https://fsprojects.github.io/FSharp.Formatting/apidocs

Defines a simple F# function `someFunction` and its associated XML documentation comments, including summary, parameter, return, example, and category tags.

```fsharp
    ///   <para>Another paragraph, see  <see cref="T:TheNamespace.SomeType"/>. </para>
    /// </summary>
    ///
    /// <param name="x">The input</param>
    ///
    /// <returns>The output</returns>
    ///
    /// <example>
    ///   Try using
    ///   <code>
    ///      open TheNamespace
    ///      SomeModule.a
    ///   </code>
    /// </example>
    ///
    /// <category>Foo</category>
    ///
    let someFunction x = 42 + x

```

--------------------------------

### Create ApiDocComment Object

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidoccomment

Constructs an ApiDocComment object by providing various documentation parts such as xmldoc, summary, remarks, parameters, returns, examples, notes, exceptions, and raw data. This constructor is essential for programmatically creating documentation comment representations.

```F#
ApiDocComment(xmldoc, summary, remarks, parameters, returns, examples, notes, exceptions, rawData)
```

--------------------------------

### CommentRegEx Property - FSharp.Formatting

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-csharpformat-mshformat

Gets the regular expression string used to match single-line comments starting with '#'. This property is abstract and must be implemented by derived classes.

```F#
this.CommentRegEx : string
```

--------------------------------

### Ignore Generated Files in .gitignore

Source: https://fsprojects.github.io/FSharp.Formatting/zero-to-hero

This .gitignore content specifies directories and files that should be ignored by Git, including .fsdocs cache, generated documentation output, and temporary files. This prevents unnecessary files from being committed to the repository.

```gitignore
# FSharp.Formatting
.fsdocs/
output/
tmp/
```

--------------------------------

### F# XML Documentation Comment Example with NamespaceDoc

Source: https://fsprojects.github.io/FSharp.Formatting/apidocs

This F# code snippet illustrates the use of XML documentation comments, including the `summary`, `remarks`, and `namespacedoc` tags. The `namespacedoc` tag is specifically used to provide documentation for the entire namespace.

```fsharp
/// <summary>
///   A module
/// </summary>
///
/// <namespacedoc>
///   <summary>A namespace to remember</summary>
///
///   <remarks>More on that</remarks>
/// </namespacedoc>
///
/// <summary>
///   Some actual comment

```

--------------------------------

### Generating iPython Notebook Output with FSharp.Formatting

Source: https://fsprojects.github.io/FSharp.Formatting/content

Describes how to generate iPython Notebook (.ipynb) output using an optional `_template.ipynb` file. It also shows how to include a mybinder badge for interactive notebook execution by referencing a `Dockerfile` and `NuGet.config`.

```markdown
[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/fsprojects/FSharp.Formatting/gh-pages?filepath=literate.ipynb)
```

--------------------------------

### F# code snippet with multiple samples and HTML structure

Source: https://fsprojects.github.io/FSharp.Formatting/codeformat

Illustrates an F# code snippet formatted with HTML, including line numbers and spans for different code elements (comments, identifiers, strings, numbers). This example shows how the F# Formatting library handles multiple snippets separated by `// [snippet: ...]` comments, producing distinct HTML blocks for each snippet and shared tooltips.

```html
<table class="pre"><tr><td class="lines"><pre class="fssnip">
<span class="l">1: 
</span><span class="l">2: 
</span><span class="l">3: 
</span><span class="l">4: 
</span><span class="l">5: 
</span><span class="l">6: 
</span><span class="l">7: 
</span></pre>
</td>
<td class="snippet"><pre class="fssnip"><span class="c">// [snippet: First sample]</span>
<span class="i">printf</span> <span class="s">"The answer is: %A"</span> <span class="n">42</span>
<span class="c">// [/snippet]</span>
<span class="c">// [snippet: Second sample]</span>
<span class="i">printf</span> <span class="s">"Hello world!"</span>
<span class="c">// [/snippet]</span>
</pre>
</td>
</tr>
</table>
```

--------------------------------

### Get CSS Stylesheet as Stream - F#

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-csharpformat-sourceformat

Gets the CSS stylesheet as a stream. This stream contains the definitions for CSS classes used by CSharpFormat for syntax highlighting, allowing it to be embedded or linked in web pages.

```F#
let getCssStream () : System.IO.Stream =
    FSharp.Formatting.CSharpFormat.SourceFormat.GetCssStream()
```

--------------------------------

### Searchable Docs Implementation

Source: https://fsprojects.github.io/FSharp.Formatting/commandline

Details on how to implement search functionality in your documentation using the generated index.json and provided scripts.

```APIDOC
## Searchable Docs

### Description
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. To add search to your own `_template.html`, you need to include specific HTML elements and a JavaScript file.

### Method
HTML/JavaScript Integration

### Endpoint
N/A

### Parameters
None

### Request Example
```html
<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>
```

### Response
Enables a search interface within the documentation, allowing users to search through content indexed in `index.json`.
```

--------------------------------

### Get CSS Stylesheet as String - F#

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-csharpformat-sourceformat

Gets the CSS stylesheet as a string. This string contains the definitions for CSS classes used by CSharpFormat for syntax highlighting, making it easy to include directly in HTML or CSS files.

```F#
let getCssString () : string =
    FSharp.Formatting.CSharpFormat.SourceFormat.GetCssString()
```

--------------------------------

### Getting Member Name in F#

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidocmember

Retrieves the name of an F# member. This is the identifier used to refer to the member within the code.

```F#
this.Name
```

--------------------------------

### Get Snippets Property (F#)

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-codeformat-formattedcontent

Retrieves the processed snippets as an array from a FormattedContent object. This is an instance member of the FormattedContent type.

```F#
let snippetsArray = formattedContent.Snippets
```

--------------------------------

### fsdocs build command

Source: https://fsprojects.github.io/FSharp.Formatting/commandline

Processes a 'docs' directory to generate API documentation for projects in a solution.

```APIDOC
## fsdocs build

### Description
Processes a `docs` directory and generates API docs for projects in the solution. It follows specific rules for API doc generation. The command accepts various options to customize the build process.

### Method
CLI Command

### Endpoint
N/A

### Parameters

#### Command Line Options

*   `--input` (string) - Input directory of content (default: `docs`)
*   `--projects` (string) - Project files to build API docs for outputs, defaults to all packable projects.
*   `--output` (string) - Output Directory (default 'output' for 'build' and 'tmp/watch' for 'watch').
*   `--ignoreuncategorized` - Disable generation of the 'Other' category in the navigation bar for uncategorized docs.
*   `--noapidocs` - Disable generation of API docs.
*   `--ignoreprojects` - Disable project cracking.
*   `--eval` - Evaluate F# fragments in scripts.
*   `--saveimages` - Save images referenced in docs.
*   `--nolinenumbers` - Don't add line numbers (default is to add line numbers).
*   `--parameters` (string) - Additional substitution parameters for templates.
*   `--nonpublic` - The tool will also generate documentation for non-public members.
*   `--nodefaultcontent` - Do not copy default content styles, javascript or use default templates.
*   `--clean` - Clean the output directory.
*   `--help` - Display this help screen.
*   `--version` - Display version information.
*   `--properties` (string) - Provide properties to dotnet msbuild, e.g. `--properties Configuration=Release Version=3.4`.
*   `--fscoptions` (string) - Additional arguments passed down as `otherflags` to the F# compiler when the API is being generated. Example: `--fscoptions " -r:MyAssembly.dll"`.
*   `--strict` - Fail if docs are missing or can't be generated.

#### Recommended Project File Settings (Alternative to CLI options)

*   `--sourceFolder` (string) - Source folder at time of component build (`<FsDocsSourceFolder>`)
*   `--sourceRepo` (string) - Source repository for github links (`<FsDocsSourceRepository>`)
*   `--mdComments` - Assume comments in F# code are markdown (`<UsesMarkdownComments>`)

### Request Example
```bash
fsdocs build
```

### Response
Reports on `.fsproj` files, indicating if they are skipped and why (e.g., project name contains '.Tests' or 'test', or missing `<GenerateDocumentationFile>true</GenerateDocumentationFile>` in the `.fsproj` file).
```

--------------------------------

### F# ApiDocNamespace Name Property

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidocnamespace

Gets the name of the namespace. This is a simple string property representing the identifier for the namespace.

```fsharp
this.Name : string
```

--------------------------------

### Generate HTML Documentation (F#)

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidocs

Generates default HTML pages for specified assemblies. It takes input components, an output directory, collection name, substitutions, and optional parameters for templates, root URLs, qualification, library directories, compiler flags, and error handling.

```F#
ApiDocs.GenerateHtml(
    inputs: ApiDocInput list,
    output: string,
    collectionName: string,
    substitutions: Substitutions,
    ?template: string,
    ?root: string,
    ?qualify: bool,
    ?libDirs: string list,
    ?otherFlags: string list,
    ?urlRangeHighlight: Uri -> int -> int -> string,
    ?onError: string -> unit
) : ApiDocModel * ApiDocsSearchIndexEntry[]
```

--------------------------------

### FSharp.Formatting fsdocs-release-notes-link ParamKey

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-templating-paramkeys

Parameter key for the release notes link in FSharp.Formatting. It provides a direct link to the release notes of a package.

```F#
ParamKeys.fsdocs-release-notes-link
```

--------------------------------

### HtmlText Property (F#)

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidochtml

Gets the HTML text content of the ApiDocHtml object. This property returns the raw HTML string.

```fsharp
this.HtmlText : string
```

--------------------------------

### ApiDocCollection CollectionName Property (F#)

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidoccollection

Gets the name of the ApiDocCollection. This property returns a string representing the collection's name.

```fsharp
this.CollectionName : string
```

--------------------------------

### FormattedSnippet Constructor

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-codeformat-formattedsnippet

Initializes a new instance of the FormattedSnippet class with a key and content.

```APIDOC
## FormattedSnippet Constructor

### Description
Initializes a new instance of the FormattedSnippet class.

### Method
Constructor

### Parameters
#### Parameters
- **key** (string) - Description of the key parameter
- **content** (string) - Description of the content parameter

### Request Example
```json
{
  "key": "exampleKey",
  "content": "exampleContent"
}
```

### Response
#### Success Response (200)
- **FormattedSnippet** (object) - An instance of the FormattedSnippet class.
```

--------------------------------

### FSharp.Formatting LiterateDocument Constructor

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-literate-literatedocument

Constructs a new LiterateDocument. It requires parameters for paragraphs, formatted tips, links, source, source file, root input folder, and diagnostics.

```F#
LiterateDocument(paragraphs: MarkdownParagraphs, formattedTips: string, links: IDictionary<string, (string * string option)>, source: LiterateSource, sourceFile: string, rootInputFolder: string option, diagnostics: SourceError array)
```

--------------------------------

### JavaScriptFormat.Preprocessors Property (F#)

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-csharpformat-javascriptformat

Retrieves the definition for preprocessor directives in JavaScript. This abstract property is used to color-code directives starting with '@'.

```fsharp
let preprocessors = formatter.Preprocessors
```

--------------------------------

### F# Module and Type Definitions with Documentation

Source: https://fsprojects.github.io/FSharp.Formatting/apidocs

Illustrates defining F# modules and types with associated documentation comments. It shows how to document types, modules, and functions, including how references to types like `Foo.Bar` and `Foo.Baz` are handled.

```fsharp
/// Contains two types [Bar] and [Foo.Baz]
module Foo =

    /// Bar is just an `int` and belongs to module [Foo]
    type Bar = int

    /// Baz contains a `Foo.Bar` as its `id`
    type Baz = { id: Bar }

    /// This function operates on `Baz` types.
    let f (b: Baz) = b.id * 42

/// Referencing [Foo3] will not generate a link as there is no type with the name `Foo3`
module Foo3 =

    /// This is not the same type as `Foo.Bar`
    type Bar = double

    /// Using the simple name for [Bar] will fail to create a link because the name is duplicated in
    /// [Foo.Bar] and in [Foo3.Bar]. In this case, using the full name works.
    let f2 b = b * 50
```

--------------------------------

### Getting Member Symbol in F#

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidocmember

Retrieves the FSharpSymbol associated with a member. This provides a programmatic handle to the member's underlying representation.

```F#
this.Symbol
```

--------------------------------

### Retrieving Member Comments in F#

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidocmember

Gets the associated comment for an F# member. This is valuable for documentation generation or displaying help text.

```F#
this.Comment
```

--------------------------------

### SyntaxHighlighter Constructors

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-csharpformat-syntaxhighlighter

Provides constructors for initializing the SyntaxHighlighter class.

```APIDOC
## SyntaxHighlighter()

### Description
Initializes a new instance of the SyntaxHighlighter class.

### Method
CONSTRUCTOR

### Endpoint
N/A

### Parameters
None

### Request Example
```csharp
var highlighter = new SyntaxHighlighter();
```

### Response
#### Success Response (200)
N/A (Constructor)

#### Response Example
N/A (Constructor)
```

--------------------------------

### Getting Member Category in F#

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidocmember

Retrieves the category of an F# member. This can be used for organizing or filtering members based on their type or purpose.

```F#
this.Category
```

--------------------------------

### Rebase Documentation Links using CLI (Text)

Source: https://fsprojects.github.io/FSharp.Formatting/apidocs

Demonstrates how to set the base URL for links in the generated documentation using the `dotnet fsdocs build` command with the `--parameters root` option. This is useful for local testing or when the documentation is hosted at a different base path than the default.

```text
dotnet fsdocs build --output public/docs --parameters root ../
```

--------------------------------

### Get Length of TokenSpan List in F#

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-codeformat-tokenspans

Returns the total number of TokenSpan elements in the list. This property returns an integer.

```fsharp
this.Length
```

--------------------------------

### Generate HTML Documentation

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidocs

Generates default HTML pages for the assemblies specified by the inputs parameter.

```APIDOC
## ApiDocs.GenerateHtml

### Description
Generates default HTML pages for the assemblies specified by the `inputs` parameter.

### Method
GET (or POST, depending on implementation context)

### Endpoint
/websites/fsprojects_github_io/fsharp_formatting/ApiDocs/GenerateHtml

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **inputs** (ApiDocInput list) - Required - the components to generate documentation for
- **output** (string) - Required - the output directory
- **collectionName** (string) - Required - the overall collection name
- **substitutions** (Substitutions) - Required - the substitutions to use in content and templates
- **template** (string) - Optional - the template to use for each documentation page
- **root** (string) - Optional - The root url of the generated documentation within the website
- **qualify** (bool) - Optional - qualify the output set by collection name, e.g. `reference/FSharp.Core/...`
- **libDirs** (string list) - Optional - Use this to specify additional paths where referenced DLL files can be found when formatting code snippets inside Markdown comments
- **otherFlags** (string list) - Optional - Additional flags that are passed to the F# compiler to specify references explicitly etc.
- **urlRangeHighlight** (Uri -> int -> int -> string) - Optional - A function that can be used to override the default way of generating GitHub links
- **onError** (string -> unit) - Optional

### Request Example
```json
{
  "inputs": [
    {
      "projectFile": "path/to/your/project.fsproj",
      "dependencies": []
    }
  ],
  "output": "./docs",
  "collectionName": "MyProject",
  "substitutions": {
    "Version": "1.0.0"
  },
  "template": "./templates/default.liquid"
}
```

### Response
#### Success Response (200)
- **apiDocModel** (ApiDocModel) - The generated API documentation model.
- **searchIndexEntries** (ApiDocsSearchIndexEntry[]) - The search index entries.

#### Response Example
```json
{
  "apiDocModel": { ... },
  "searchIndexEntries": [
    { ... },
    { ... }
  ]
}
```
```

--------------------------------

### Get F# Checker Instance

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-codeformat-codeformatter

Returns an instance of the FSharpChecker, which is likely used for interacting with the F# compiler services to perform analysis.

```F#
fsChecker () : FSharpChecker
```

--------------------------------

### VisualBasicFormat Preprocessors Property

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-csharpformat-visualbasicformat

Gets the list of Visual Basic preprocessor directives. This property aids in the correct parsing and formatting of preprocessor statements.

```fsharp
let vbPreprocessors = visualBasicFormatter.Preprocessors
```

--------------------------------

### Getting Member Return Information in F#

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidocmember

Retrieves information about the return value of an F# member, typically used in tooltips or documentation summaries.

```F#
this.ReturnInfo
```

--------------------------------

### Specify project information for template replacement

Source: https://fsprojects.github.io/FSharp.Formatting/literate

Demonstrates how to load a template file and provide project-specific information as parameters for replacement within the template. This is useful for customizing generated documentation.

```fsharp
// Load the template & specify project information
let projTemplate = source + "template-project.html"

let projInfo =
    [ "fsdocs-authors", "Tomas Petricek"
      "fsdocs-source-link", "https://github.com/fsprojects/FSharp.Formatting"
      "fsdocs-collection-name", "F# Formatting" ]

```

--------------------------------

### Retrieving Obsolete Message in F#

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidocmember

Gets the message associated with an obsolete F# member. If the member is not obsolete or has no message, an empty string is returned.

```F#
this.ObsoleteMessage
```

--------------------------------

### Create fsdocs Template Files

Source: https://fsprojects.github.io/FSharp.Formatting/upgrade

Creates template files for F# scripts and notebooks, which can be used by fsdocs for co-generation. Also adds these files to Git version control.

```bash
touch docs/_template.fsx
touch docs/_template.ipynb
git add docs/_template.fsx
git add docs/_template.ipynb
```

--------------------------------

### Preprocessors Property - FSharp.Formatting

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-csharpformat-mshformat

Gets the regular expression string used to highlight operators, often used for preprocessor directives. This property is abstract.

```F#
this.Preprocessors : string
```

--------------------------------

### Generate Markdown Documentation (F#)

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidocs

Generates default Markdown pages for specified assemblies. It accepts input components, an output directory, collection name, substitutions, and optional parameters for templates, root URLs, qualification, library directories, compiler flags, and error handling.

```F#
ApiDocs.GenerateMarkdown(
    inputs: ApiDocInput list,
    output: string,
    collectionName: string,
    substitutions: Substitutions,
    ?template: string,
    ?root: string,
    ?qualify: bool,
    ?libDirs: string list,
    ?otherFlags: string list,
    ?urlRangeHighlight: Uri -> int -> int -> string,
    ?onError: string -> unit
) : ApiDocModel * ApiDocsSearchIndexEntry[]
```

--------------------------------

### FsiEvaluatorConfig Constructors

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-literate-evaluation-fsievaluatorconfig

Details on how to create instances of the FsiEvaluatorConfig type.

```APIDOC
## Constructor FsiEvaluatorConfig

### Description
Initializes a new instance of the `FsiEvaluatorConfig` class.

### Method
CONSTRUCTOR

### Endpoint
N/A

### Parameters
None

### Request Example
```fsharp
let config = FsiEvaluatorConfig()
```

### Response
#### Success Response (200)
Returns an instance of `FsiEvaluatorConfig`.

### Response Example
```fsharp
val config : FsiEvaluatorConfig
```
```

--------------------------------

### Keywords Property - FSharp.Formatting

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-csharpformat-mshformat

Gets the list of MSH keywords. This property is abstract and intended to be overridden to provide the specific keywords for MSH syntax highlighting.

```F#
this.Keywords : string
```

--------------------------------

### Integrate Search into HTML Template

Source: https://fsprojects.github.io/FSharp.Formatting/commandline

Provides HTML and JavaScript snippets required to add a search functionality to custom documentation templates. This includes defining search input, display areas, and including the necessary script.

```html
<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>
```

--------------------------------

### Get ToolTip Property (F#)

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-codeformat-formattedcontent

Retrieves a string containing ToolTip elements for all snippets within a FormattedContent object. This is an instance member of the FormattedContent type.

```F#
let toolTipString = formattedContent.ToolTip
```

--------------------------------

### Generate Markdown Documentation

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidocs

Generates default Markdown pages for the assemblies specified by the inputs parameter.

```APIDOC
## ApiDocs.GenerateMarkdown

### Description
Generates default Markdown pages for the assemblies specified by the `inputs` parameter.

### Method
GET (or POST, depending on implementation context)

### Endpoint
/websites/fsprojects_github_io/fsharp_formatting/ApiDocs/GenerateMarkdown

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **inputs** (ApiDocInput list) - Required - the components to generate documentation for
- **output** (string) - Required - the output directory
- **collectionName** (string) - Required - the overall collection name
- **substitutions** (Substitutions) - Required - the substitutions to use in content and templates
- **template** (string) - Optional - the template to use for each documentation page
- **root** (string) - Optional - The root url of the generated documentation within the website
- **qualify** (bool) - Optional - qualify the output set by collection name, e.g. `reference/FSharp.Core/...`
- **libDirs** (string list) - Optional - Use this to specify additional paths where referenced DLL files can be found when formatting code snippets inside Markdown comments
- **otherFlags** (string list) - Optional - Additional flags that are passed to the F# compiler to specify references explicitly etc.
- **urlRangeHighlight** (Uri -> int -> int -> string) - Optional - A function that can be used to override the default way of generating GitHub links
- **onError** (string -> unit) - Optional

### Request Example
```json
{
  "inputs": [
    {
      "projectFile": "path/to/your/project.fsproj",
      "dependencies": []
    }
  ],
  "output": "./docs_md",
  "collectionName": "MyProject",
  "substitutions": {
    "Version": "1.0.0"
  },
  "template": "./templates/markdown.liquid"
}
```

### Response
#### Success Response (200)
- **apiDocModel** (ApiDocModel) - The generated API documentation model.
- **searchIndexEntries** (ApiDocsSearchIndexEntry[]) - The search index entries.

#### Response Example
```json
{
  "apiDocModel": { ... },
  "searchIndexEntries": [
    { ... },
    { ... }
  ]
}
```
```

--------------------------------

### HaskellFormat Constructor

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-csharpformat-haskellformat

Initializes a new instance of the HaskellFormat class.

```APIDOC
## HaskellFormat Constructor

### Description
Initializes a new instance of the HaskellFormat class.

### Method
Constructor

### Endpoint
N/A

### Parameters
None

### Request Example
```
new HaskellFormat()
```

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Access Defined Links in MarkdownDocument (F#)

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-markdown-markdowndocument

Illustrates how to get the dictionary of explicitly defined links within a MarkdownDocument. This is useful for managing or inspecting hyperlink references.

```F#
let definedLinks = markdownDoc.DefinedLinks
```

--------------------------------

### Retrieving Member Type Arguments in F#

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidocmember

Gets a list of type arguments for a generic F# member. This is essential for understanding the generic constraints and types used.

```F#
this.TypeArguments
```

--------------------------------

### Substitutions Type Members

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-templating-substitutions

Documentation for the instance and static members of the Substitutions type.

```APIDOC
## Substitutions Type

### Description
A list of parameters for substituting in templates, indexed by parameter keys.

### Namespace
FSharp.Formatting.Templating

### Assembly
FSharp.Formatting.Common.dll

### Instance Members

#### `this.Head`

##### Description
Returns the first parameter in the substitutions list.

##### Returns
`ParamKey * string`

#### `this.IsEmpty`

##### Description
Checks if the substitutions list is empty.

##### Returns
`bool`

#### `this[index]`

##### Description
Retrieves a parameter at a specific index in the substitutions list.

##### Parameters
- **index** (`int`) - The index of the parameter to retrieve.

##### Returns
`ParamKey * string`

#### `this.Length`

##### Description
Returns the number of parameters in the substitutions list.

##### Returns
`int`

#### `this.Tail`

##### Description
Returns the rest of the parameters in the substitutions list, excluding the first one.

##### Returns
`(ParamKey * string) list`

### Static Members

#### `List.Empty`

##### Description
Returns an empty substitutions list.

##### Returns
`(ParamKey * string) list`
```

--------------------------------

### FSharp.Formatting fsdocs-theme ParamKey

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-templating-paramkeys

Parameter key for the theme in FSharp.Formatting. It specifies the documentation theme being used.

```F#
ParamKeys.fsdocs-theme
```

--------------------------------

### Getting Custom Operation Name in F#

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidocmember

Retrieves the custom operation name for an F# member, specifically when it's associated with the CustomOperationAttribute. Returns None if not applicable.

```F#
this.CustomOperationName
```

--------------------------------

### F# Module with Cross-references using <seealso>

Source: https://fsprojects.github.io/FSharp.Formatting/apidocs

Demonstrates using the `<seealso>` tag within XML documentation comments in an F# module to create cross-references between functions.

```fsharp
module Forest =

    /// <summary>
    /// Find at most <c>limit</c> foxes in current forest
    ///
    /// See also: <seealso cref="M:App.Forest.findSquirrels(System.Int32)"/>
    /// </summary>
    let findFoxes (limit : int) = []

    /// <summary>
    /// Find at most <c>limit</c> squirrels in current forest
    ///
    /// See also: <seealso cref="M:App.Forest.findFoxes(System.Int32)"/>
    /// </summary>
    let findSquirrels (limit : int) = []

```

--------------------------------

### Id Property (F#)

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidochtml

Gets the optional ID of the ApiDocHtml object when rendered to HTML. This property returns an Option type which may contain a string value.

```fsharp
this.Id : string option
```

--------------------------------

### Getting Member URL Base Name in F#

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidocmember

Retrieves the base name for generating documentation URLs for an F# item. This is the part of the URL without the base path.

```F#
this.UrlBaseName
```

--------------------------------

### Generate F# Documentation Model

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidocs

Generates a documentation model from specified inputs. It handles collection name, substitutions, and optional parameters like qualification, library directories, compiler flags, root URL, URL range highlighting, error handling, and file extensions.

```F#
ApiDocs.GenerateModel(inputs, collectionName, substitutions, ?qualify, ?libDirs, ?otherFlags, ?root, ?urlRangeHighlight, ?onError, ?extension)
```

--------------------------------

### Retrieving Member Modifiers in F#

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidocmember

Gets a list of modifiers applied to an F# member, such as 'public', 'private', 'static', etc. These define the member's accessibility and behavior.

```F#
this.Modifiers
```

--------------------------------

### Get Last Write Times F#

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-common-menu

Retrieves the last modification times for files within a given input path. Returns a list of DateTime objects.

```fsharp
getLastWriteTimes input
```

--------------------------------

### FSharp.Formatting fsdocs-repository-link ParamKey

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-templating-paramkeys

Parameter key for the repository link in FSharp.Formatting. It provides the URL to the source code repository.

```F#
ParamKeys.fsdocs-repository-link
```

--------------------------------

### StringRegEx Property - FSharp.Formatting

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-csharpformat-mshformat

Gets the regular expression string used to match string and character literals. This abstract property defines the pattern for recognizing literal values.

```F#
this.StringRegEx : string
```

--------------------------------

### Configure FAKE for Documentation Generation

Source: https://fsprojects.github.io/FSharp.Formatting/upgrade

Adjusts the build.fsx file to include targets for generating and releasing documentation using fsdocs and Git.

```fsharp
Target.create "GenerateDocs" (fun _ ->
   Shell.cleanDir ".fsdocs"
   DotNet.exec id "fsdocs" "build --clean" |> ignore
)

Target.create "ReleaseDocs" (fun _ ->
    Git.Repository.clone "" projectRepo "temp/gh-pages"
    Git.Branches.checkoutBranch "temp/gh-pages" "gh-pages"
    Shell.copyRecursive "output" "temp/gh-pages" true |> printfn "%A"
    Git.CommandHelper.runSimpleGitCommand "temp/gh-pages" "add ." |> printfn "%s"
    let cmd = sprintf "commit -a -m \"Update generated documentation for version %s\"" release.NugetVersion
    Git.CommandHelper.runSimpleGitCommand "temp/gh-pages" cmd |> printfn "%s"
    Git.Branches.push "temp/gh-pages"
)
```

--------------------------------

### FSharp.Formatting fsdocs-source ParamKey

Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-templating-paramkeys

Parameter key for the source in FSharp.Formatting. It provides general information about the source of the documentation page.

```F#
ParamKeys.fsdocs-source
```
Tokens:
Raw