Docfx

https://dotnet.github.io/docfx/
Admin
Docfx is a static site generator that converts .NET assemblies, XML documentation comments, REST API...
Tokens:89,322
Snippets:936
Trust Score:9.7
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Custom startup script in main.js

Source: https://dotnet.github.io/docfx/docs/template.html

Use the 'start' option in main.js to run custom startup scripts. The example shows an empty function where you can add your code.

```javascript
export default {
  start: () => {
    // Startup script goes here
  },
}
__

```

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

### Add startup script in main.js

Source: https://dotnet.github.io/docfx/tutorial/walkthrough/advanced_walkthrough.html

Use the 'start' option in main.js to run a startup script when the site loads. The example shows an empty function where you can add your code.

```javascript
export default {
  start: () => {
    // Startup script goes here
  },
}
```

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

### API Heading preview example

Source: https://dotnet.github.io/docfx/docs/api-page.html

Example of an API heading with preview flag.

```yaml
body:
- api4: Foo(int baz)
  preview: true
  src: https://dotnet.github.io/docfx
__
```

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

### Directory structure example

Source: https://dotnet.github.io/docfx/docs/links-and-cross-references.html

Example directory structure used to illustrate relative file links.

```text
|- docfx.json
|- file1.md
|- subfolder
   |- file2.md
```

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

### Include example with filepath

Source: https://dotnet.github.io/docfx/spec/docfx_flavored_markdown.html

Example of including a markdown file from the includes folder. The included file should be excluded from build.

```markdown
[!INCLUDE [my-markdown-block](../../includes/my-markdown-block.md)]
```

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

### Install docfx from local nupkg source

Source: https://dotnet.github.io/docfx/index.html

Installs docfx as a .NET Global Package from a local source. Use --prerelease to include prerelease versions.

```bash
dotnet tool update docfx -g --prerelease --source ./
```

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

### Initialize a new docfx project

Source: https://dotnet.github.io/docfx/index.html

Creates a new docfx project in the current directory. Walks through the setup process interactively.

```bash
docfx init
```

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

### Heading block example

Source: https://dotnet.github.io/docfx/docs/api-page.html

Example of a Heading block in the body array.

```yaml
body:
- h4: This is an H4
__
```

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

### Metadata Configuration Example

Source: https://dotnet.github.io/docfx/reference/docfx-json-reference.html

Basic structure for defining source files and destination directories for metadata generation.

```json
{
  "metadata": [
    {
      "src": [
        {
          "files": ["**/*.csproj"],
          "exclude": [ "**/bin/**", "**/obj/**" ],
          "src": "../src"
        }
      ],
      "dest": "api"
    }
  ]
}
```

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

### YAML example of parameters

Source: https://dotnet.github.io/docfx/docs/api-page.html

Shows a YAML structure for parameters with fields like name, type, default, description, preview, and deprecated. The example includes a generic type parameter and a state parameter with a default value and preview flag.

```yaml
body:
- parameters:
  - name: T
    description: A generic type.
  - name: state
    type: string
    default: 'new'
    description: The operation status.
    preview: true
  - name: removed
    type: boolean
    deprecated: true
```

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

### Install docfx with dotnet tool update

Source: https://dotnet.github.io/docfx/index.html

Installs the latest docfx tool globally using the .NET CLI. Requires .NET SDK 8.0 or higher.

```bash
dotnet tool update -g docfx
```

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

### Constructor YAML Representation

Source: https://dotnet.github.io/docfx/docs/dotnet-yaml-format.html

Example showing C# constructor definitions and their corresponding YAML mapping.

```csharp
namespace System
{
    public sealed class String
    {
        public String();
        public String(char[] chars);
    }
}
```

```yaml
- uid: System.String.#ctor
  id: #ctor
  name.csharp: String()
  fullName.csharp: System.String.String()
- uid: System.String.#ctor(System.Char[])
  id: #ctor(System.Char[])
  name.csharp: String(Char[])
  fullName.csharp: System.String.String(System.Char[])
```

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

### Inline Elements Example

Source: https://dotnet.github.io/docfx/docs/api-page.html

YAML example showing how to use inline elements in a list block. It demonstrates a plain string, a link, and a mix of both as a nested list.

```yaml
body:
- list:
  - a string
  - text: a link
    url: https://dotnet.github.io/docfx
  - - a mix of string and
    - text: link
      url: https://dotnet.github.io/docfx

```

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

### Method YAML Representation

Source: https://dotnet.github.io/docfx/docs/dotnet-yaml-format.html

Example showing C# method definitions and their corresponding YAML mapping.

```csharp
namespace System
{
    public sealed class String
    {
        public String ToString();
        public String ToString(IFormatProvider provider);
    }
}
```

```yaml
- uid: System.String.ToString
  id: ToString
  name.csharp: ToString()
  fullName.csharp: System.String.ToString()
- uid: System.String.ToString(System.IFormatProvider)
  id: ToString(System.IFormatProvider)
  name.csharp: ToString(IFormatProvider)
  fullName.csharp: System.String.ToString(System.IFormatProvider)
```

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

### Layout produced by tag example

Source: https://dotnet.github.io/docfx/docs/rest-api-docs.html

This output shows the layout generated from the previous Swagger example, with operations grouped under 'Basic', 'Advanced', and 'Other APIs'.

```text
Basic
├─ get_contacts
Advanced
├─ get_contacts
├─ set_contacts
Other APIs
├─ delete_contacts
```

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

### C# code example with Azure Blob

Source: https://dotnet.github.io/docfx/spec/docfx_flavored_markdown.html

Example C# code that creates a BlobServiceClient, creates a container, and uploads a file. This code is used to illustrate the highlight feature.

```csharp
using System;
using Azure;
using Azure.Storage;
using Azure.Storage.Blobs;

class Program
{
    static void Main(string[] args)
    {
        // Define the connection string for the storage account
        string connectionString = "DefaultEndpointsProtocol=https;AccountName=<your-account-name>;AccountKey=<your-account-key>;EndpointSuffix=core.windows.net";

        // Create a new BlobServiceClient using the connection string
        var blobServiceClient = new BlobServiceClient(connectionString);

        // Create a new container
        var container = blobServiceClient.CreateBlobContainer("mycontainer");

        // Upload a file to the container
        using (var fileStream = File.OpenRead("path/to/file.txt"))
        {
            container.UploadBlob("file.txt", fileStream);
        }
    }
}
```

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

### Example master page _master.html

Source: https://dotnet.github.io/docfx/tutorial/intro_template.html

A simple HTML master page that includes the {{!body}} placeholder.

```html
<html>
    <head></head>
    <body>
        {{!body}}
    <body>
</html>

```

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

### Namespace YAML Representation

Source: https://dotnet.github.io/docfx/docs/dotnet-yaml-format.html

Example showing the flat namespace structure where ID and UID are identical.

```csharp
namespace System.IO
{
}
```

```yaml
uid: System.IO
id: System.IO
name: System.IO
fullName: System.IO
```

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

### Build documentation with docfx build

Source: https://dotnet.github.io/docfx/docs/basic-concepts.html

Run the build step to generate the documentation site. Append `--serve` to start a local web server for previewing the output.

```bash
docfx build path/to/docfx.json
```

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

### Serve a built website and open browser with docfx --serve

Source: https://dotnet.github.io/docfx/reference/docfx-cli-reference/docfx-serve.html

Hosts a local static website and launches the default web browser when the hosted website starts. Uses the --open-browser option.

```bash
docfx --serve _site --open-browser
```

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

### Basic Overwrite Section with YAML header

Source: https://dotnet.github.io/docfx/tutorial/intro_overwrite_files.html

Basic example of an Overwrite Section in an Overwrite File. The YAML header must start with the `uid` property and be enclosed between triple-dashed lines. The Markdown content following the header is transformed into the `conceptual` property of the Overwrite Model.

```markdown
---
uid: microsoft.com/docfx/Contacts
some_property: value
---
Further description for `microsoft.com/docfx/Contacts`
__
```

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

### Build and serve with browser

Source: https://dotnet.github.io/docfx/reference/docfx-cli-reference/docfx-build.html

Builds the site and then serves it, opening the default browser.

```bash
docfx build --serve --open-browser
```

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

### Run docfx and serve with browser

Source: https://dotnet.github.io/docfx/reference/docfx-cli-reference/docfx.html

Runs the metadata, build, and pdf commands, then serves the generated site and opens it in the default browser.

```text
docfx --serve --open-browser
```

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

### Inheritance block example

Source: https://dotnet.github.io/docfx/docs/api-page.html

Example of an Inheritance block in the body array.

```yaml
body:
- inheritance:
  - text: object
    url: https://learn.microsoft.com/dotnet/api/system.object
  - text: string
    url: https://learn.microsoft.com/dotnet/api/system.string
__
```

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

### Example PDF Configuration

Source: https://dotnet.github.io/docfx/docs/pdf.html

A sample configuration demonstrating how to enable PDF generation, specify a cover page, include a TOC, and enable headers/footers on those pages.

```yaml
pdf: true
pdfCoverPage: cover.html
pdfTocPage: true
pdfHeaderFooterOnCover: true
pdfHeaderFooterOnToc: true
items:
- name: Getting Started
  href: getting-started.md
```

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

### List block example

Source: https://dotnet.github.io/docfx/docs/api-page.html

Example of a List block in the body array.

```yaml
body:
- list:
  - text: object
    url: https://learn.microsoft.com/dotnet/api/system.object
  - text: string
    url: https://learn.microsoft.com/dotnet/api/system.string
__
```

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

### Facts block example

Source: https://dotnet.github.io/docfx/docs/api-page.html

Example of a Facts block in the body array.

```yaml
body:
- facts:
  - name: Namespace
    value:
    - text: System.Runtime
      url: https://learn.microsoft.com/dotnet/api/system.runtime
  - name: Assembly
    value: System.Runtime.dll
__
```

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

### Build and serve the docset

Source: https://dotnet.github.io/docfx/index.html

Builds the docset and serves it locally at http://localhost:8080. Use this to preview the website.

```bash
docfx docfx.json --serve
```

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

### Code block example

Source: https://dotnet.github.io/docfx/docs/api-page.html

Example of a Code block in the body array.

```yaml
body:
- code: public class System.String {}
__
```

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

### Markdown block example

Source: https://dotnet.github.io/docfx/docs/api-page.html

Example of a Markdown block in the body array.

```yaml
body:
- markdown: |
    This is a **markdown** block with [links](https://dotnet.github.io/docfx).
__
```

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

### Mermaid gantt chart example

Source: https://dotnet.github.io/docfx/docs/markdown.html

Example of a Mermaid gantt chart diagram.

```mermaid
gantt
    title Git Issues - days since last update
    dateFormat  X
    axisFormat %s

    section Issue19062
    71   : 0, 71
    section Issue19401
    36   : 0, 36
    section Issue193
    34   : 0, 34
    section Issue7441
    9    : 0, 9
    section Issue1300
    5    : 0, 5
```

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

### Build static site with default config

Source: https://dotnet.github.io/docfx/reference/docfx-cli-reference/docfx-build.html

Runs the build with the default docfx.json configuration file.

```bash
docfx build
```

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

### Mermaid pie chart example

Source: https://dotnet.github.io/docfx/docs/markdown.html

Example of a Mermaid pie chart diagram.

```mermaid
pie
    title Pie Chart
    "Dogs" : 50
    "Cats" : 25
    "Birds" : 25
```

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

### Document Processor Build Order Example

Source: https://dotnet.github.io/docfx/tutorial/howto_build_your_own_type_of_documentation_with_custom_plug-in.html

An illustration of the execution order for build steps A and B across documents D1, D2, and D3.

```text
A.Prebuild([D1, D2, D3]) returns [D1, D2, D3]
B.Prebuild([D1, D2, D3]) returns [D1, D2, D3]
Parallel(
  A.Build(D1) -> B.Build(D1),
  A.Build(D2) -> B.Build(D2),
  A.Build(D3) -> B.Build(D3)
)
A.Postbuild([D1, D2, D3])
B.Postbuild([D1, D2, D3])
```

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

### Serve a built website with docfx serve

Source: https://dotnet.github.io/docfx/reference/docfx-cli-reference/docfx-serve.html

Hosts a local static website generated by the docfx build command. The _site directory is the default output directory for docfx build.

```bash
docfx serve _site
```

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

### API Heading deprecated example

Source: https://dotnet.github.io/docfx/docs/api-page.html

Example of an API heading with deprecated flag.

```yaml
body:
- api4: Foo(int bar)
  deprecated: true
  src: https://dotnet.github.io/docfx
__
```

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

### Mermaid user journey diagram example

Source: https://dotnet.github.io/docfx/docs/markdown.html

Example of a Mermaid user journey diagram.

```mermaid
journey
  title My working day
  section Go to work
    Make tea: 5: Me
    Go upstairs: 3: Me
    Do work: 1: Me, Cat
  section Go home
    Go downstairs: 5: Me
    Sit down: 3: Me
```

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

### Generated sitemap.xml example

Source: https://dotnet.github.io/docfx/reference/docfx-json-reference.html

Shows the generated sitemap.xml output for the above configuration. Demonstrates how baseUrl, changefreq, priority, and lastmod are applied per URL; note the priority for the GettingStarted URL remains 0.3 because fileOptions order matters.

```xml
<?xml version="1.0" encoding="utf-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://dotnet.github.io/docfx/api/System.String.html</loc>
    <lastmod>2001-01-01T00:00:00.00+08:00</lastmod>
    <changefreq>monthly</changefreq>
    <priority>0.3</priority>
  </url>
  <url>
    <loc>https://dotnet.github.io/docfx/conceptual/GettingStarted.html</loc>
    <lastmod>2017-09-21T10:00:00.00+08:00</lastmod>
    <changefreq>daily</changefreq>
    <priority>0.3</priority>
  </url>
  <url>
    <loc>https://dotnet.github.io/docfx/ReadMe.html</loc>
    <lastmod>2017-09-21T10:00:00.00+08:00</lastmod>
    <changefreq>monthly</changefreq>
    <priority>0.1</priority>
  </url>
</urlset>
```

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

### Mermaid flowchart example

Source: https://dotnet.github.io/docfx/docs/markdown.html

Example of a Mermaid flowchart diagram. Supported only in the modern template.

```mermaid
flowchart LR

A[Hard] -->|Text| B(Round)
B --> C{Decision}
C -->|One| D[Result 1]
C -->|Two| E[Result 2]
```

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

### List available templates

Source: https://dotnet.github.io/docfx/reference/docfx-cli-reference/docfx-template.html

Prints all the available template names.

```bash
docfx template list
```

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

### Configure templates in docfx.json

Source: https://dotnet.github.io/docfx/docs/basic-concepts.html

Example `docfx.json` configuration for the build step, specifying the output directory and a list of templates. Docfx searches the templates in the order listed, with the first match taking precedence.

```json
{
  "build": {
    //...
    "output": "_site",
    "template": [
      "default",
      "modern",
      "templates/mytemplate"
    ]
  }
}
```

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

### Generic Method Definition Example

Source: https://dotnet.github.io/docfx/docs/dotnet-yaml-format.html

Example of C# generic method definitions for the System.Tuple class.

```csharp
namespace System
{
    public static class Tuple
    {
        public static Tuple<T1> Create<T1>(T1 item1);
        public static Tuple<T1, T2> Create<T1, T2>(T1 item1, T2 item2);
    }
}
```

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

### Initialize DocFX configuration

Source: https://dotnet.github.io/docfx/docs/publish-azure-devops.html

Run this command to generate a docfx.json configuration file, which defines how DocFX builds your documentation.

```bash
docfx init -q
```

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

### PlantUML Sequence Diagram Example

Source: https://dotnet.github.io/docfx/docs/markdown.html

Example of a PlantUML sequence diagram. The diagram is rendered by the PlantUML extension.

```plantuml
```plantuml
Bob -> Alice : hello
```
```

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

### Reference Spec YAML Example

Source: https://dotnet.github.io/docfx/docs/dotnet-yaml-format.html

Example of a spec member in a reference, describing how to compose a complex generic type.

```yaml
references:
- uid: System.Collections.Generic.Dictionary{System.String,System.Collections.Generic.List{System.Int32}}
  name.csharp: Dictionary<String, List<Int32>>
  fullName.csharp: System.Collections.Generic.Dictionary<System.String, System.Collections.Generic.List<System.Int32>>
  spec.csharp:
  - uid: System.Collections.Generic.Dictionary`2
    name: Dictionary
    fullName: System.Collections.Generic.Dictionary
    isExternal: true
  - name: <
    fullName: <
  - uid: System.String
    name: String
    fullName: System.String
    isExternal: true
  - name: ', '
    fullName: ', '
  - uid: System.Collections.Generic.List`1
    name: List
    fullName: System.Collections.Generic.List
    isExternal: true
  - name: <
    fullName: <
  - uid: System.Int32
    name: Int32
    fullName: System.Int32
    isExternal: true
  - name: '>'
    fullName: '>'
  - name: '>'
    fullName: '>'
```

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

### Source Link Exclusion Example

Source: https://dotnet.github.io/docfx/reference/docfx-json-reference.html

Example of using sourceLinkExclude to hide View Source links for specific generated files based on path patterns.

```json
{
  "metadata": [
    {
      "src": [{ "files": ["**/bin/Release/**/MyLibrary.dll"] }],
      "dest": "api",
      "sourceLinkExclude": [
        "**/ExampleGenerator/**"
      ]
    }
  ]
}
```

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

### Configure syntax highlighting in main.js

Source: https://dotnet.github.io/docfx/docs/template.html

Use the 'configureHljs' option in main.js to customize highlight.js. The example shows an empty function for customization.

```javascript
export default {
  configureHljs: (hljs) => {
    // Customize hightlight.js here
  },
}
__

```

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

### C# example for Spec Identifier

Source: https://dotnet.github.io/docfx/docs/dotnet-yaml-format.html

Shows a C# class with a method that uses generic type parameters, arrays, and pointers, as referenced in Example 2.2.

```csharp
namespace Foo
{
   public class Bar
   {
      public unsafe List<String> FooBar<TArg>(int[] arg1, byte* arg2, TArg arg3, List<TArg[]> arg4)
      {
          return null;
      }
   }
}
```

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

### Custom JavaScript entry point

Source: https://dotnet.github.io/docfx/docs/template.html

Place this in my-template/public/main.js to set the default theme to dark and add icon links in the header. The example adds GitHub and Twitter icons.

```javascript
/* file: my-template/public/main.js */
export default {
  defaultTheme: 'dark',
  iconLinks: [
    {
      icon: 'github',
      href: 'https://github.com/dotnet/docfx',
      title: 'GitHub'
    },
    {
      icon: 'twitter',
      href: 'https://twitter.com',
      title: 'Twitter'
    }
  ]
}
__

```

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

### Alternative template configuration

Source: https://dotnet.github.io/docfx/docs/template.html

Another example of configuring a custom template in docfx.json, using 'templates' (plural) instead of 'template'. The example includes 'default' and 'my-template'.

```json
{
  "build": {
    "templates": [
      "default",
      "my-template" // <-- Path to custom template
    ]
  }
}
__

```

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

### Run docfx with default config

Source: https://dotnet.github.io/docfx/reference/docfx-cli-reference/docfx.html

Runs the metadata, build, and pdf commands using the default docfx.json configuration file.

```text
docfx
```

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

### build - Basic configuration

Source: https://dotnet.github.io/docfx/reference/docfx-json-reference.html

Configuration options applied for the docfx build command, including content, resource, and globalMetadata.

```json
{
  "build": {
    "content": ["**/*.{md|yml}"],
    "resource": ["**/media/**"],
    "globalMetadata": {
      "_appTitle": "My App"
    }
  }
}
```
Tokens:
Raw