repository·main·Indexed 26 days ago
https://github.com/dotnet/docfxA tool for building technical documentation sites, supporting landing pages, Markdown, and API reference documentation for .NET and REST APIs. It features a two-stage process consisting of a metadata step to extract documentation from .NET source code or assemblies and a build step to convert YAML and Markdown into HTML. docfx can be installed as a .NET global tool or integrated as a library via the Docfx.App package.
In the DocFX metadata format, an Item is the basic unit representing a documentation section (e.g., a namespace, class, or method).
[ParentUID][Separator][ID].., :, /, and \.Items can be hierarchical. A parent item contains its children via its children property, and a child item points to its parent via its parent property.
The DocFX template system controls how final output files are rendered. It works by loading data models (produced by Document Processors) and transforming them into output files based on their document type (e.g., conceptual for Markdown, Toc for toc.md).
Key components:
conceptual).Docfx is a documentation generator that supports the following workflows:
C# and VB (though VB output is rendered in C# format) and saves it in YAML format.docfx.msbuild NuGet package is currently in a pre-release version.The DocFX Document Schema is a JSON-based media type used to define the structure of DocFX documents. It is designed to provide three primary functions:
type and properties) to validate document data.summary property as having a markup interpretation using DocFX Flavored Markdown).Schema files should follow the convention of using the .schema.json suffix.
You can embed Mermaid diagrams using standard Markdown code blocks with the mermaid language tag.
Requirement: Mermaid diagrams are only supported when using the modern template.
Supported diagram types include flowchart, pie, gantt, journey, and classDiagram.
flowchart LR
A[Hard] -->|Text| B(Round)
B --> C{Decision}
C -->|One| D[Result 1]
C -->|Two| E[Result 2]When developing or extending DocFX plugins to support RTF files, you can implement hyperlink updating so that relative links to .rtf files are automatically converted to links to the generated .html files during the build process.
To ensure links are correctly processed, the hyperlinks in your source RTF files must follow these rules:
foo\bar.rtf, ../foobar.rtf/foo.rtf, c:\foo\bar.rtf, http://foo.bar/, mailto:foo@bar.foobarOpen your RTF plugin library project in Visual Studio and configure the following:
Docfx.Utility.System.Core, System.Web, and System.Xml.Linq.In your document processor implementation, you need to implement the following logic:
FixLink: A helper method to update the link target (e.g., changing .rtf to .html). Use RelativePath to ensure links are generated correctly.CollectLinksAndFixDocument: A method to traverse the document and apply link fixes.Save: Modify the Save method to report or handle the processed links..dll to the Plugins folder of your DocFX project..rtf file targeting another .rtf file and save it.docfx build.html file contains the updated link pointing to the .html version of the target.DocFX uses a normalized file path to track links reliably. A normalized path:
docfx.json) using the ~/ prefix.../, ./, or //./ instead of \.~/foo/bar.rtfDocfx uses the Markdig engine and supports several extensions by default (Mathematics, Emphasis Extras, Auto Identifiers, Media Links, Pipe Tables, Auto Links, and Emoji).
To use additional custom extensions, you have two options:
If you are building a custom tool using Docfx.App, configure the BuildOptions in your C# code:
Set the build.markdownEngineProperties.markdigExtensions property in your docfx.json file. Provide a list of extension names (e.g., "Abbreviations", "Footnotes").
Note: Custom configuration of extensions via the build.markdownEngineProperties.markdigExtensions property is not supported when using certain build modes (refer to documentation for specific constraints).
{
"build": {
"markdownEngineProperties": {
"markdigExtensions": [
"Abbreviations",
"Footnotes"
]
}
}
}To extend DocFX with custom file support (e.g., converting .rtf to HTML), you must implement two primary interfaces: IDocumentProcessor and IDocumentBuildStep within a C# class library.
Responsible for:
GetProcessingPriority.Load.Save.BuildSteps property.UpdateHref.Responsible for transforming document content via three lifecycle methods:
Prebuild: Reconstruct or filter documents (e.g., removing documents based on rules).Build: Transform content (e.g., converting RTF content to HTML).Postbuild: Perform cross-document transformations (e.g., extracting link text from titles).net8.0 or later.System.Composition, Docfx.Plugins, and Docfx.Common.[Export] attribute to register your classes with the DocFX plugin system.Before automating builds, ensure you have a docfx.json configuration file in your repository. You can generate a default configuration file by running the docfx init command with the -q (quiet) flag. This file defines your input/output directories and build settings.
docfx init -qDocfx allows you to highlight specific lines or ranges in a code snippet using a custom syntax. The syntax follows the pattern [!code-language[](path?highlight=line-numbers)].
[!code-csharp[](media/Program.cs?highlight=2,5-7,9-)]