docfx-plus

KO | EN

gitlite — search

#react #ai #typescript #machine-learning #linux #nodejs #macos #java #windows #awesome #cli #kubernetes #vue #open-source

(★ 10)

A template and a tool for enhancing DocFx.

docfx-plus Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

![DotMake Docfx-Plus Logo](https://raw.githubusercontent.com/dotmake-build/docfx-plus/master/images/logo-wide.svg "DotMake Docfx-Plus Logo")

# DotMake Docfx-Plus

A template and a tool for enhancing [DocFx](https://github.com/dotnet/docfx).

This project includes two parts:

- The `docfx-plus` **template** which extends DocFx's `modern` template to fix many UI problems and behaviors. 
  It looks and feels more similar to Microsoft's Learn site.

- The `docfx-plus` **tool** which is a wrapper around `docfx` tool, which at runtime patches the internals to fix some problems;
  currently mainly for advanced support of XML Comments (xmldocs) `<code>` blocks.
  This wrapper is developed because these changes cannot be applied in the template (or in a plugin as it's too late for metadata (`.yml`) changes).
  The tool can also convert/migrate your existing `SHFB` projects completely to `docfx` projects.

This project was mainly done for migrating our projects' docs from [SHFB (Sandcastle Help File Builder)](https://github.com/EWSoftware/SHFB) 
which is still very stable but its theme and architecture was outdated.
`SHFB` was used for many years mainly because of its excellent `<code>` block support and now we put these features into `docfx`.

[**Live Demo**](https://dotmake.build/command-line/api/) - API docs for our other project [DotMake Command-Line](https://github.com/dotmake-build/command-line).

[![Nuget](https://img.shields.io/nuget/v/docfx-plus?style=for-the-badge&logo=nuget)](https://www.nuget.org/packages/docfx-plus)

![docfx-plus-template-light](https://raw.githubusercontent.com/dotmake-build/docfx-plus/master/images/docfx-plus-template-light.png)

![docfx-plus-template-light](https://raw.githubusercontent.com/dotmake-build/docfx-plus/master/images/docfx-plus-template-dark.png)

## Getting started

Install the dotnet tool from [NuGet](https://www.nuget.org/packages/docfx-plus).

```console
dotnet tool install --global docfx-plus
```

Or just update to the latest (also installs if not exists):

```console
dotnet tool update --global docfx-plus
```

### Prerequisites

- .NET SDK 8.0 and later. The .NET CLI (`dotnet` command) is included with the [.NET SDK](https://learn.microsoft.com/en-us/dotnet/core/sdk).

## Usage

### Dotnet tool usage

Just use `docfx-plus` command instead of `docfx` command with same subcommands, arguments and options:

```console
docfx-plus init --yes

docfx-plus --serve

docfx-plus metadata

docfx-plus build
```

Refer to [DocFx Commandline Reference](https://dotnet.github.io/docfx/reference/docfx-cli-reference/overview.html) for more details.

#### Converting existing `SHFB` projects to `docfx` projects

The tool also adds new `convert` command to convert/migrate your existing `SHFB (Sandcastle Help File Builder)` projects completely to `docfx` projects:
- Project file (`.shfbproj`) will be converted to `docfx.json`
- Content Layout files (`.content`) will be converted to `toc.yml`
- MAML Topic files (`.aml`) will be converted to Markdown files (`.md`)
- Namespace summaries will be converted to overwrite files (`.md`)
- Other content files like images will be copied
- By default `content` subfolder will be rebased to `docs`  
  and `icons`, `media` subfolders will be rebased to `images`
  to match `docfx` conventions.

Convert the first found `.shfbproj` file in current directory to `docfx` subfolder:
```console
docfx-plus convert -o docfx
```

Convert a specific `.shfbproj` file to `docfx` path:
```console
docfx-plus convert path/Documentation.shfbproj -o path/docfx
```

All options for `convert` command:
```console
Usage:
  docfx-plus convert [<shfb-project-file>] [options]

Arguments:
  <shfb-project-file>  The path to the SHFB project file (`.shfbproj`). By default, the first found `.shfbproj` file in
                       current directory is used

Options:
  -o, --output <output>                             The output base directory to write converted DocFx project files.
                                                    [required]
  -dl, --docs-location <docs-location>              The subfolder under DocFx project, to use for markdown (`.md`)
                                                    files. [default: docs]
  -il, --images-location <images-location>          The subfolder under DocFx project, to use for image files.
                                                    [default: images]
  -al, --api-location <api-location>                The subfolder under DocFx project, to use for generated API
                                                    metadata (`.yml`) files. [default: api]
  -ol, --overwrites-location <overwrites-location>  The subfolder under DocFx project, to use for overwrite (`.md` or
                                                    `.yml`) files. [default: overwrites]
  -rc, --rebase-content                             Whether to rebase `content` subfolder from SHFB to `docs` location
                                                    when converting. [default: True]
  -ri, --rebase-images                              Whether to rebase `icons` and `media` subfolders from SHFB to
                                                    `images` location when converting. [default: True]
  -?, -h, --help                                    Show help and usage information
```

### Template usage

Edit your `docfx.json` and update the template property so that you are able to use the theme:
```json
"template": [
  "default",
  "modern",
  "docfx-plus"
]
```
And ensure `outputFormat` is not set to a value other than `mref` (the default value if not set, which means ManagedReference). 
For example using value `apiPage` will not make use of our theme because for that mode, 
`docfx` internally generates the HTML, most of which is not customizable in the template.  
Use these `metadata` settings for best results:
```json
"metadata": [
  {
    "memberLayout": "separatePages",
    "categoryLayout": "nested"
  }
]
```
The template can also be used alone with regular `docfx` tool, however it's recommended to use `docfx-plus` tool
which already bundles the template and in addition provides important fixes for `<code>` blocks.

If you want to use the theme with the regular `docfx` tool, you can export it via:
```console
docfx-plus template export docfx-plus
```
This will export the bundled `docfx-plus` template to `_exported_templates` subfolder, which then can be consumed as:
```json
"template": [
  "default",
  "modern",
  "_exported_templates/docfx-plus"
]
```

Refer to [DocFx Config Reference](https://dotnet.github.io/docfx/reference/docfx-json-reference.html) for more details.

## `docfx-plus` **tool** features

- Support region includes (`<code source="..." region="...">`) across more language files (e.g. `.vb`, `.js`, `.aspx`).  
  Support the same region extensions for markdown code snippet source files (`[!code-csharp[](Program.cs#region)]`).  
  This will be useful especially when migrating from `SHFB`.
  
  In `.vb` source files, regions defined like this can now be included:
  ```vb
  #Region "Name"

#End Region
  ```
  
  In `.js` source files, regions defined like this can now be included:
  ```js
  //#region Name
  
  //#endregion
  ``` 
  
  In xml-based source files, regions defined like this can now be included (just like `SHFB`): 
  ```xml

```
  This is in addition to `docfx` default format:
  ```xml

```
  
  `.aspx`, `.csproj`, `.slnx`, `.config` are also added to `docfx` default xml-based formats `.xml`, `.xaml`, `.html`, `.cshtml`, `.vbhtml`.
 
- Always ensure correct indentation for both xml comments code blocks and markdown code snippets.  
  Some source files or `<code>` contents can contain tab characters which can cause inconsistent indentation.

Convert tab (`\t`) characters to spaces. 
  Define and use default tab sizes for common code file extensions (e.g. `2` spaces for xml-based files or `4` spaces for c-based files),
  so that code keeps correct indentation when some lines start with tabs and some starts with spaces.
 
  Support `tabSize` attribute (`<code tabSize="2">`) to override default tabSize for a language.

- Consistent line break handling inside `<code>` blocks so that code is always rendered correctly in the html.

Additionally normalize new lines inside of parent elements, which contain `<code>` blocks
  to prevent Yaml multi-line problems (`.yml` generated by `docfx`).
  This way text surrounding code blocks will not break Yaml due to inconsistent indentation.

- Support nested `<code>` blocks in your XML Comments (xmldocs), for merging code even from different regions, just like `SHFB`:
  ```xml
  <code language="cs">
    <code source="Class1.cs" region="Region1" />
    <code source="Class2.cs" region="Region2" />
  </code>
  ```

Literal code can also be mixed around nested `<code>` blocks.
  ```xml
  <code language="cs">
    // The new line below will be significant but above will not

// New lines above or below will be significant

// The new line above will be significant but below will not
  </code>
  ```
  Indentation from source files and literal code will all be normalized.

- Support `title` attribute (`<code title="Custom">`) which is used when showing as code tab title instead of the language.

- If `codeSourceBasePath` from `metadata` in `docfx.json` is a relative path,
  convert it to be relative to the `docfx.json` (`docfx` originally treats it relative to the working directory, which is wrong).
  
  In markdown files, allow to reference code snippet source files relative to `codeSourceBasePath` option in `docfx.json` 
  via new special prefix `~~/` (note the double tilde). For example:
  ```
  [!code-csharp[](~~/Program.cs)]
  [!code-csharp[](~~/../SubFolder/Program.cs)]
  ```
  If `codeSourceBasePath` option is not set, this will fallback to `docfx.json` project root so it will behave like already supported `~/` prefix.

Convert backslashes (`\`) in code block's source attribute (`<code source="...">`) to forward slashes (`/`)  
  so that they are resolved correctly even when building docs on linux (e.g. when running in a Github Pages workflow which are usually linux based).  
  Since .NET 8, `System.IO.Path` methods does not do backslash mapping in Unix file paths  
  but we want to support existing projects which may have `<code source="...">` with backslashes all over the source code.

- `NamespaceDoc` support just like `SHFB`.  
    Namespace comments can be specified and maintained in your source code by adding an empty `NamespaceDoc` class to each namespace.  
    XML Comments (`<summary>` and `<remarks>` tags) from these classes will be extracted and assigned to the containing namespaces in the docs.
          
    ```c#
    namespace DotMake.CommandLine
    {
        /// <summary>
        /// This is the root namespace of this library, it includes the CLI attributes and CLI parser/runner.
        /// <para />
        /// <para>The main classes in this namespace are:</para>
        /// <list type="bullet">
        ///     <item><see cref="CliCommandAttribute"/> is the attribute which specifies a class that represents a command which is a specific action that the command line application performs.</item>
        ///     <item><see cref="CliOptionAttribute"/> is the attribute which specifies a class property that represents an option which is a named parameter and a value for that parameter, that is used on the command line.</item>
        /// </list>
        /// </summary>
        [System.Runtime.CompilerServices.CompilerGenerated]
        internal class NamespaceDoc
        {
        }
    }
    ```
          
    `NamespaceDoc` classes will be found even if your API filter excludes them but themselves will not be included in the docs,
    only their XML Comments assigned to the containing namespaces will be displayed.  
    You can optionally make them private or internal and mark them with a `CompilerGenerated` attribute.

- For markdown alerts, use bold text in the first line as the title of the alert:
  ```
  > [!note]
  > **Project Road Map**
  > This alert contains a custom title.
         
  > [!caution]
  > **security note**
  > Do not tape your password to the underside of your keyboard.
  ```
 
## `docfx-plus` **template** features

- In namespace, class, enum or member pages use `Name Type` format as the title e.g. `CliContext Class` instead of `Class CliContext`.
  
  Display `Definition` heading after the title heading.
  
  Don't break the namespace into link parts next to `Namespace:` because e.g. the root namespace may not exist and cause a HTTP 404.
  
  Fix heading margins (`<h1>`, `<h2>` ...).
  
  ![docfx-plus-template-feature1](https://raw.githubusercontent.com/dotmake-build/docfx-plus/master/images/docfx-plus-template-feature1.png)

- Display namespace members, class members and enum fields with tables with subtle borders.
  
  Display inherited members and extension methods together with other members (in their own member type group),
  instead of displaying them as a huge and isolated list under the class definition section.  
  Display `(Inherited from BaseClass)` note in the description.  
  Sort inherited members along with other members by name.

![docfx-plus-template-feature2](https://raw.githubusercontent.com/dotmake-build/docfx-plus/master/images/docfx-plus-template-feature2.png)
 
- Elegant rendering of `<code>` blocks with white background and subtle borders.
  
  Group sibling `<code>` blocks which are for different languages (e.g. `vb` following `cs`), and display them as tabs.

```xml
  <code source="Class1.cs" />
  <code source="Class1.vb" />
  ```
  
  If there is text between `<code>` blocks or if they are for same language, they will not be grouped and will be displayed separately.

Display always visible "code copy" button on the right-side of tabs.

Add `cshtml-razor` grammar for `highlight.js`.
  
  ![docfx-plus-template-feature3](https://raw.githubusercontent.com/dotmake-build/docfx-plus/master/images/docfx-plus-template-feature3.png)
 
- On member pages, display overloads with indentation separately from definition section and fix sub-heading levels (`<h2>`, `<h3>` ...).
  
  If no overloads, display single member.

![docfx-plus-template-feature4](https://raw.githubusercontent.com/dotmake-build/docfx-plus/master/images/docfx-plus-template-feature4.png)

- Display values for `enum` fields along with name and description and sort them by values.

![docfx-plus-template-feature5](https://raw.githubusercontent.com/dotmake-build/docfx-plus/master/images/docfx-plus-template-feature5.png)

- Display `Obsolete` badge if class, enum or member has `ObsoleteAttribute` attribute 
  and an in addition display an alert `div` under the badge if `ObsoleteAttribute` has a message.

![docfx-plus-template-feature6](https://raw.githubusercontent.com/dotmake-build/docfx-plus/master/images/docfx-plus-template-feature6.png)

- Elegant rendering of TOC tree.

Highlight current tree node.

Remove root node `Namespaces` which causes unnecessary nesting and display all namespaces as root (though fixed in `v2.78.4` of `docfx`).

![docfx-plus-template-feature7](https://raw.githubusercontent.com/dotmake-build/docfx-plus/master/images/docfx-plus-template-feature7.png)
 
- Add icon links to top toolbar via new template property `_appIconLinks` directly in `docfx.json` (no need to override `layout/_master.tmpl`):
 
  ```json
  "globalMetadata": {
      "_appIconLinks": [
        {
          "icon": "github",
          "href": "https://github.com/dotmake-build/command-line",
          "title": "GitHub"
        }
      ]
  }
  ```

Fix header nav brand logo, title and buttons wrapping on phone and tablet sizes.
  
  ![docfx-plus-template-feature8](https://raw.githubusercontent.com/dotmake-build/docfx-plus/master/images/docfx-plus-template-feature8.png)

- Fix some URL issues:
 
  Use `./` instead of `index.html` for app logo by default to prevent canonical URL issues for search engines.
  
  Fix URLs starting with app relative path `~/` for TOC.  
  This is because we can't use e.g. `./` for `href` in `toc.yml`; we get `CircularTocInclusion` error
  as it tries to load itself at `./toc.yml`.  
  This way, we can use `~/.` as a workaround in `toc.yml` (we want to use clean directory URL and avoid using `index.html`)

## DocFx Tips:

### Using README.md in your docs:
  
- When you want to reference your repository's `README.md` file, you can create `index.md` next to `docfx.json` with contents:
  ```
  [!include [getting-started](../README.md)]
  ```
  Note that upper case `!INCLUDE` as noted in docs, may not work on some machines (probably due to turkish-I bug in docfx).  
  The path should be relative to the containing file.  
  `index.md` needs to exist anyway otherwise homepage (`/`) will not work so it's better to include `README.md` in this file 
  if there is nothing else to put on the homepage.
  
- Another way: if you define external .md files as content in `docfx.json` like this:
  ```
  "build": {
    "content": [
      {
        "files": ["README.md"],
        "src": "../",
        "dest": "docs"
      }
    ],
  ```
  dot-dot notation can not appear in `files` but it can appear in `src`.  
  `src` is relative to the `docfx.json` folder (config root).  
  The `dest` means the output subfolder (under `_site` by default) for the corresponding html file, e.g. `README.html`.
  
  Then in `toc.yml` you can reference the .md file:
  ```
  - name: Readme
    href: ~/../README.md
  - name: Prerequisites
    href: ~/../README.md#prerequisites
  ```
  Note that the path should match `src` and not `dest`. Using `~/` in case `toc.yml` is in a subfolder and not in config root.  
  You can also put the # fragment but the file will not be splitted, it will just be a fragment link.

### Publish to GitHub Pages:

Create a workflow file in your repository, e.g. `publish-docs.yml` file in `.github\workflows` folder with these contents:

```yml
# Your GitHub workflow file under .github/workflows/
# Trigger the action on push to main
on:
  push:
    branches:
      - main

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  actions: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false
  
jobs:
  publish-docs:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
    - name: Checkout
      uses: actions/checkout@v3

- name: Dotnet Setup
      uses: actions/setup-dotnet@v3
      with:
        dotnet-version: 8.x

# Install latest version of docfx-plus
    - run: dotnet tool update -g docfx-plus

# Build docs in this repository via docfx-plus
    - run: docfx-plus docs/docfx.json

- name: Upload artifact
      uses: actions/upload-pages-artifact@v3
      with:
        # Upload HTML output of the docs build
        path: 'docs/_site'

- name: Deploy to GitHub Pages
      id: deployment
      uses: actions/deploy-pages@v4
```

Then enable GitHub Actions for your repository's Pages settings as described here:  
[Publishing with a custom GitHub Actions workflow](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow)

Now whenever you commit, your action will run automatically and publish your docs.

### Full `docfx.json` sample:

Refer to [docfx.json](https://github.com/dotmake-build/command-line/blob/main/docs/docfx.json) from our other project [DotMake Command-Line](https://github.com/dotmake-build/command-line).

```js
{
  "$schema": "https://raw.githubusercontent.com/dotnet/docfx/main/schemas/docfx.schema.json",
  "metadata": [
    {
      "src": [
        {
          "src": "../src",
          "files": [
            "DotMake.CommandLine/DotMake.CommandLine.csproj"
          ]
        }
      ],
      "dest": "api", 
      "codeSourceBasePath": "../src/DotMake.CommandLine/", 
      "memberLayout": "separatePages",
      "categoryLayout": "nested"
    }
  ],
  "build": {
    "content": [
      {
        "files": [
          "**/*.{md,yml}"
        ],
        "exclude": [
          "_site/**",
          "apidocs/**"
        ]
      },
      {
        //Handle separately because we use different dest
        "files": ["*.md"],
        "src": "apidocs",
        "dest": "api"
      }
    ],
    "resource": [
      {
        "files": [
          "images/**"
        ]
      }, 
      {
        "files": [
          "logo-wide.svg",
        ], 
        "src": "../images",
        "dest": "images"
      }
    ],
    "output": "_site",
    "template": [
      "default",
      "modern",
      "docfx-plus"
    ],
    //"plugins": [], 
    "globalMetadata": {
      "_appName": "DotMake Command-Line",
      "_appLogoPath": "images/logo-wide.svg",
      //"_appLogoUrl": "./",
      "_appFaviconPath": "images/favicon.ico", 
      "_appIconLinks": [
        {
          "icon": "github",
          "href": "https://github.com/dotmake-build/command-line",
          "title": "GitHub"
        }
      ],
      "_enableSearch": true,
      "pdf": false
    }
  }
}
```

## Building

We provide some `.cmd` batch scripts in `build` folder for easier building:
```console
1. Build Cli.cmd
2. Build Nuget Packages.cmd
3. Build Api Docs WebSite.cmd         
```

Output results can be found in `publish` folder, for example:
```console
DotMake.DocfxPlus.Cli-net8.0

docfx-plus.1.0.0.nupkg
```

## Sample Outputs

### These documentation projects are converted from SHFB to Docfx-Plus:
- [Sandcastle Help File Builder Documentation](https://dotmake.build/docfx-plus/SandcastleBuilder/)
- [Sandcastle MAML Guide](https://dotmake.build/docfx-plus/SandcastleMAMLGuide/)
- [Sandcastle XML Comments Guide](https://dotmake.build/docfx-plus/XMLCommentsGuide/)
- [Small Earth Technology ANT+ Class Library](https://dotmake.build/docfx-plus/AntPlus/)

### These documentation projects are created by Docfx-Plus:
- [DotMake Command-Line](https://dotmake.build/command-line/)
- [DotMake Svg-Sprite](https://dotmake.build/svg-sprite/)

docfx-plus

docfx-plus Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

docfx-plus

docfx-plus Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README