### Initialize a New Docfx Project Source: https://github.com/dotnet/docfx/blob/main/docs/index.md Create a new docfx project in the current directory. This command will guide you through the setup process. ```bash docfx init ``` -------------------------------- ### Install docfx as a global tool Source: https://github.com/dotnet/docfx/blob/main/README.md Installs the docfx command-line interface globally on your system. This command requires the .NET SDK to be installed. ```bash dotnet tool install -g docfx ``` -------------------------------- ### GitHub Actions Workflow for Publishing to GitHub Pages Source: https://github.com/dotnet/docfx/blob/main/docs/index.md Example GitHub Actions workflow to automate the publishing of docfx generated documentation to GitHub Pages. It checks out code, sets up .NET, installs docfx, builds the site, and deploys it. ```yaml # 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 - run: dotnet tool update -g docfx - run: docfx /docfx.json - name: Upload artifact uses: actions/upload-pages-artifact@v3 with: # Upload entire repository path: '/_site' - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v4 ``` -------------------------------- ### Install Docfx as .NET Global Package Source: https://github.com/dotnet/docfx/blob/main/docs/index.md Installs or updates the Docfx .NET global tool from a local source. Use the --prerelease flag if installing a pre-release version. The --source ./ flag points to the current directory where the nupkg was downloaded. ```bash dotnet tool update docfx -g --prerelease --source ./ ``` -------------------------------- ### Install Latest Docfx CLI Source: https://github.com/dotnet/docfx/blob/main/docs/index.md Install or update the docfx command-line interface to the latest version. Ensure .NET SDK is installed. ```bash dotnet tool update -g docfx ``` -------------------------------- ### Master Page Example Source: https://github.com/dotnet/docfx/blob/main/docs/tutorial/intro_template.md An example demonstrating how a master page (`_master.html`) and a template (`conceptual.html.tmpl`) work together to render HTML content. ```html with mustache {{!body}} ``` ```mustache {{!master('_master.html')}} Hello World ``` -------------------------------- ### Generated Sitemap XML Example Source: https://github.com/dotnet/docfx/blob/main/docs/reference/docfx-json-reference.md An example of the sitemap.xml file generated by Docfx based on the provided configuration. ```xml https://dotnet.github.io/docfx/api/System.String.html 2001-01-01T00:00:00.00+08:00 monthly 0.3 https://dotnet.github.io/docfx/conceptual/GettingStarted.html 2017-09-21T10:00:00.00+08:00 daily 0.3 https://dotnet.github.io/docfx/ReadMe.html 2017-09-21T10:00:00.00+08:00 monthly 0.1 ``` -------------------------------- ### Specify Resource Files for Build Source: https://github.com/dotnet/docfx/blob/main/docs/reference/docfx-json-reference.md An example of how to specify an array of resource files to be included in the project. ```json { "build": { "resource": ["**/*.png"] } } ``` -------------------------------- ### Example Block Include Source: https://github.com/dotnet/docfx/blob/main/docs/docs/markdown.md Example of a block include referencing a markdown file located in the includes directory. ```markdown [!INCLUDE [my-markdown-block](../../includes/my-markdown-block.md)] ``` -------------------------------- ### Build Docfx Project Source: https://github.com/dotnet/docfx/blob/main/docs/docs/basic-concepts.md Command to initiate the Docfx build process. Appending `--serve` will start a local web server for previewing the output. ```shell docfx build path/to/docfx.json ``` -------------------------------- ### Issue2623 Method Example Source: https://github.com/dotnet/docfx/blob/main/test/docfx.Snapshot.Tests/SamplesTest.SeedMarkdown/BuildFromProject.Class1.verified.md Provides an example usage for the Issue2623 method. This snippet demonstrates object instantiation and method invocation. ```csharp MyClass myClass = new MyClass(); void Update() { myClass.Execute(); } ``` -------------------------------- ### Partial Template Example Source: https://github.com/dotnet/docfx/blob/main/docs/spec/docfx_document_schema.md An example of a partial template file used with the xref syntax. This template defines how properties like 'title' and 'description' are rendered when referenced. ```mustache {{title}}: {{{description}}} ``` -------------------------------- ### Issue2723 Method Example Source: https://github.com/dotnet/docfx/blob/main/test/docfx.Snapshot.Tests/SamplesTest.SeedMarkdown/BuildFromProject.Class1.verified.md Demonstrates a loop and range initialization within the context of Issue2723. Note the handling of special characters and angle brackets. ```csharp for (var i = 0; i > 10; i++) // & " ' var range = new Range { Min = 0, Max = 10 }; ``` ```csharp var range = new Range { Min = 0, Max = 10 }; ``` -------------------------------- ### Specify Content Files for Build Source: https://github.com/dotnet/docfx/blob/main/docs/reference/docfx-json-reference.md An example of how to specify an array of content files to be included in the project using glob patterns. ```json { "build": { "content": ["**/*.{md,yml}"] } } ``` -------------------------------- ### Build project and run tests Source: https://github.com/dotnet/docfx/blob/main/README.md Commands to build the docfx project using the .NET CLI and execute the project's tests. Ensure you have the .NET SDK installed. ```bash dotnet build dotnet test ``` -------------------------------- ### C# Console Output Source: https://github.com/dotnet/docfx/blob/main/RELEASENOTE.md A simple C# console application example. ```csharp Console.WriteLine("Hello world"); ``` -------------------------------- ### Define Global Metadata for All Files Source: https://github.com/dotnet/docfx/blob/main/docs/reference/docfx-json-reference.md Applies metadata to every file in the documentation. This example sets the application title and enables search. ```json { "build": { "globalMetadata": { "_appTitle": "DocFX website", "_enableSearch": "true" } } } ``` -------------------------------- ### JSON API Options Example Source: https://github.com/dotnet/docfx/blob/main/test/docfx.Snapshot.Tests/SamplesTest.SeedMarkdown/BuildFromProject.Inheritdoc.Issue9736.JsonApiOptions.verified.md This JSON structure represents an example of API options, potentially related to resource linking or relationships within an API. ```json { "type": "articles", "id": "4309", "relationships": { "author": { "links": { "self": "/api/shopping/articles/4309/relationships/author", "related": "/api/shopping/articles/4309/author" } } } } ``` -------------------------------- ### Configure Docfx Templates Source: https://github.com/dotnet/docfx/blob/main/docs/docs/basic-concepts.md Example configuration in `docfx.json` to specify custom templates. Docfx searches these templates in the order listed. ```json { "build": { //... "output": "_site", "template": [ "default", "modern", "templates/mytemplate" ] } } ``` -------------------------------- ### REST Extensibility Configuration Source: https://github.com/dotnet/docfx/blob/main/RELEASENOTE.md Configuration example for enabling REST extensibility using `rest.tagpage` and `rest.operationpage` plugins in DocFX. ```json "rest.tagpage": {}, "rest.operationpage": {} ``` -------------------------------- ### Issue4017 Method Remarks Example Source: https://github.com/dotnet/docfx/blob/main/test/docfx.Snapshot.Tests/SamplesTest.SeedMarkdown/BuildFromProject.Class1.verified.md Provides a code snippet for the remarks section of Issue4017, demonstrating a simple update method. ```csharp void Update() { myClass.Execute(); } ``` -------------------------------- ### JavaScript Console Output Source: https://github.com/dotnet/docfx/blob/main/RELEASENOTE.md A simple JavaScript console log example. ```javascript console.log('hello world'); ``` -------------------------------- ### Renderer File Naming Convention Example Source: https://github.com/dotnet/docfx/blob/main/docs/tutorial/intro_template.md Illustrates the naming convention for Renderer files, specifying document type, output extension, and the optional '.primary' qualifier. ```text /- some_template/ |- conceptual.html.primary.tmpl \- conceptual.mta.json.tmpl ``` -------------------------------- ### Mustache Partial Syntax Example Source: https://github.com/dotnet/docfx/blob/main/docs/tutorial/intro_template.md Demonstrates how to define and use Mustache partials within Renderer files for code reuse. Partials must end with '.tmpl.partial'. ```mustache Inside Partial {{ name }} ``` ```mustache Inside Renderer {{ >part }} ``` ```mustache Inside Renderer Inside Partial {{ name }} ``` -------------------------------- ### List Available Docfx Templates Source: https://github.com/dotnet/docfx/blob/main/docs/docs/basic-concepts.md Command to list all embedded templates available within the Docfx installation. ```shell docfx template list ``` -------------------------------- ### Navigation Bar TOC Configuration Source: https://github.com/dotnet/docfx/blob/main/docs/docs/table-of-contents.md Configures the main navigation bar by referencing different TOC directories. This example sets up 'Docs' and 'API' entries in the navigation. ```yaml - name: Docs href: docs/ - name: API href: api/ ``` -------------------------------- ### Instantiating Generic Cat Class Source: https://github.com/dotnet/docfx/blob/main/test/docfx.Snapshot.Tests/SamplesTest.SeedMarkdown/CatLibrary.Cat-2.verified.md Example of creating an instance of the generic Cat class. Note the use of 'unsafe' context due to pointer usage in GetFeetLength. ```csharp var a = new Cat(object, int)(); int catNumber = new int(); unsafe { a.GetFeetLength(catNumber); } ``` -------------------------------- ### Underscore Prefix for Private Fields Source: https://github.com/dotnet/docfx/blob/main/samples/seed/articles/csharp_coding_standards.md Start private fields with an underscore. ```csharp private readonly Guid _userId = Guid.NewGuid(); ``` -------------------------------- ### Configure File-Specific Metadata Source: https://github.com/dotnet/docfx/blob/main/docs/reference/docfx-json-reference.md Sets metadata that is associated with specific files based on glob patterns. This example configures priority and keywords. ```json { "build": { "fileMetadata": { "priority": { "**.md": 2.5, "spec/**.md": 3 }, "keywords": { "obj/docfx/**": ["API", "Reference"], "spec/**.md": ["Spec", "Conceptual"] }, "_noindex": { "articles/**/article.md": true } } } } ``` -------------------------------- ### Domain Independent Markdown Link Source: https://github.com/dotnet/docfx/blob/main/docs/docs/links-and-cross-references.md Create domain-independent links to local resources by starting the URL with '/'. ```markdown [my-file](/my-file.html) ``` -------------------------------- ### Issue4017 Method Example Source: https://github.com/dotnet/docfx/blob/main/test/docfx.Snapshot.Tests/SamplesTest.SeedMarkdown/BuildFromProject.Class1.verified.md Shows how to hook into a message deleted event and handle the event. This includes checking cache and logging message details. ```csharp public void HookMessageDeleted(BaseSocketClient client) { client.MessageDeleted += HandleMessageDelete; } public Task HandleMessageDelete(Cacheable cachedMessage, ISocketMessageChannel channel) { // check if the message exists in cache; if not, we cannot report what was removed if (!cachedMessage.HasValue) return; var message = cachedMessage.Value; Console.WriteLine($"A message ({message.Id}) from {message.Author} was removed from the channel {channel.Name} ({channel.Id}):" + Environment.NewLine + message.Content); return Task.CompletedTask; } ``` -------------------------------- ### Install npm dependencies and build templates Source: https://github.com/dotnet/docfx/blob/main/README.md Commands to manage Node.js package dependencies and build site templates using npm. This is part of the docfx build process for templates. ```bash npm install npm run build ``` -------------------------------- ### Create and serve a docfx website locally Source: https://github.com/dotnet/docfx/blob/main/README.md Initializes a new docfx project with default settings and then builds and serves the documentation site locally. Navigate to https://localhost:8080 to view the site. ```bash docfx init -y docfx build docfx_project\docfx.json --serve ``` -------------------------------- ### Get a contact by id Source: https://github.com/dotnet/docfx/blob/main/test/Docfx.Build.RestApi.Tests/TestData/contacts-operations.md Gets a specified contact. You use the object ID (GUID) to identify the target contact. ```APIDOC ## GET /contacts/{object_id} ### Description Gets a specified contact. You use the object ID (GUID) to identify the target contact. On success, returns the [Contact] object for the specified contact; otherwise, the response body contains error details. For more information about errors, see [Error Codes and Error Handling]. ### Method GET ### Endpoint https://graph.windows.net/{tenant_id}/contacts/{object_id}?{api_version} ### Parameters #### Path Parameters - **object_id** (GUID) - Required - The object ID of the contact to retrieve. ### Response #### Success Response (200) - **[Contact] object** - The requested contact object. ``` -------------------------------- ### Tab Syntax Explanation Source: https://github.com/dotnet/docfx/blob/main/docs/docs/markdown.md Illustrates the Markdown syntax for creating tabs. A tab is defined by a header followed by a link starting with `#tab/` and an ID. ```markdown # [Tab Display Name](#tab/tab-id) ``` -------------------------------- ### Filter APIs by UID Regex Source: https://github.com/dotnet/docfx/blob/main/docs/docs/dotnet-api-docs.md Define `apiRules` in a filter configuration file to include or exclude APIs based on their `UID` using regular expressions. This example includes APIs starting with `Microsoft.DevDiv.SpecialCase` and excludes all others starting with `Microsoft.DevDiv`. ```yaml apiRules: - include: uidRegex: ^Microsoft\.DevDiv\.SpecialCase - exclude: uidRegex: ^Microsoft\.DevDiv ``` -------------------------------- ### Serve Generated Documentation and Open Browser Source: https://github.com/dotnet/docfx/blob/main/docs/reference/docfx-cli-reference/docfx.md Builds the documentation site, serves it locally, and automatically opens the default web browser to view it. ```powershell docfx --serve --open-browser ``` -------------------------------- ### YAML Header Example Source: https://github.com/dotnet/docfx/blob/main/docs/docs/markdown.md Use a YAML header at the top of a Markdown file to provide metadata, such as a unique identifier (UID). ```markdown --- uid: fileA --- # This is fileA ... ``` -------------------------------- ### Merge specified API metadata files Source: https://github.com/dotnet/docfx/blob/main/docs/reference/docfx-cli-reference/docfx-merge.md This example shows how to merge specified API metadata files into a single YAML file. Note that the `docfx merge` command is currently broken. ```powershell docfx merge ``` -------------------------------- ### Serve Website and Open Browser Source: https://github.com/dotnet/docfx/blob/main/docs/reference/docfx-cli-reference/docfx-serve.md Host a website generated by `docfx build` and automatically launch the default web browser to view it. This is useful for quickly previewing your generated site. ```powershell docfx --serve _site --open-browser ``` -------------------------------- ### Build and Serve Static Site Contents Source: https://github.com/dotnet/docfx/blob/main/docs/reference/docfx-cli-reference/docfx-build.md Builds static site contents with the default docfx.json configuration, then serves the generated site and opens it in the default web browser. ```pwsh docfx build --serve --open-browser ``` -------------------------------- ### LoggerMessageGenerator Example Source: https://github.com/dotnet/docfx/blob/main/test/docfx.Snapshot.Tests/SamplesTest.SeedMarkdown/BuildFromProject.SourceGenerator.verified.md This method demonstrates logging a critical message with a string parameter using LoggerMessageGenerator. Ensure an ILogger instance is provided. ```csharp [LoggerMessage(EventId = 0, Level = LogLevel.Critical, Message = "Log: {text}")] public static void Log(ILogger logger, string text) ``` -------------------------------- ### Docfx Configuration for .NET Project Metadata Source: https://github.com/dotnet/docfx/blob/main/docs/docs/basic-concepts.md Example of a docfx.json configuration snippet specifying .NET project files for metadata extraction. Ensure the 'src' and 'dest' properties are correctly set for your project structure. ```json { "metadata": [ { "src": [ { "files": [ "src/MyProject.Abc/*.csproj", "src/MyProject.Xyz/*.csproj" ], "src": "path/to/csprojs" } ], "dest": "api" } ], //... } ``` -------------------------------- ### Basic Usage of docfx serve Source: https://github.com/dotnet/docfx/blob/main/docs/reference/docfx-cli-reference/docfx-serve.md Host a website that was generated by the `docfx build` command. The command will serve files from the specified directory. ```powershell docfx serve _site ``` -------------------------------- ### C# XML Documentation Comment Example Source: https://github.com/dotnet/docfx/blob/main/docs/docs/basic-concepts.md Illustrates the use of XML documentation comments in C# to generate API documentation. Ensure comments are correctly formatted for Docfx to parse. ```csharp ///

/// Calculates the age of a person on a certain date based on the supplied date of birth. Takes account of leap years, /// using the convention that someone born on 29th February in a leap year is not legally one year older until 1st March /// of a non-leap year. ///

/// Individual's date of birth. /// Date at which to evaluate age at. /// Age of the individual in years (as an integer). /// This code is not guaranteed to be correct for non-UK locales, as some countries have skipped certain dates /// within living memory. public static int AgeAt(this DateOnly dateOfBirth, DateOnly date) { int age = date.Year - dateOfBirth.Year; return dateOfBirth > date.AddYears(-age) ? --age : age; } ``` -------------------------------- ### Initialize DocFX Configuration Source: https://github.com/dotnet/docfx/blob/main/docs/docs/publish-azure-devops.md Use this command to create a basic `docfx.json` configuration file in your project. This file is essential for DocFX to generate your documentation. ```bash docfx init -q ``` -------------------------------- ### Spec Identifier Examples in C# and YAML Source: https://github.com/dotnet/docfx/blob/main/docs/docs/dotnet-yaml-format.md Illustrates how C# code constructs involving generic types, arrays, and pointers are represented using spec identifiers in YAML. ```csharp namespace Foo { public class Bar { public unsafe List FooBar(int[] arg1, byte* arg2, TArg arg3, List arg4) { return null; } } } ``` ```yaml references: - uid: System.Collections.Generic.List{System.String} - uid: System.Int32[] - uid: System.Byte* - uid: {TArg} - uid: System.Collections.Generic.List{{TArg}[]} ``` -------------------------------- ### Get contacts Source: https://github.com/dotnet/docfx/blob/main/test/Docfx.Build.RestApi.Tests/TestData/contacts-operations.md Gets a collection of contacts. You can add OData query parameters to the request to filter, sort, and page the response. ```APIDOC ## GET /contacts ### Description Gets a collection of contacts. You can add OData query parameters to the request to filter, sort, and page the response. For more information, see [Supported Queries, Filters, and Paging Options]. On success, returns a collection of [Contact] objects; otherwise, the response body contains error details. For more information about errors, see [Error Codes and Error Handling]. ### Method GET ### Endpoint https://graph.windows.net/{tenant_id}/contacts?{api_version}[odata_query_parameters] ### Response #### Success Response (200) - **value** (array) - A collection of [Contact] objects. ``` -------------------------------- ### Main Method Signature Source: https://github.com/dotnet/docfx/blob/main/test/docfx.Snapshot.Tests/SamplesTest.SeedMarkdown/BuildFromCSharpSourceCode.CSharp.verified.md Represents the entry point of the application. It accepts an array of strings as arguments. ```csharp public static void Main(string[] args) ``` -------------------------------- ### HelloWorld Method Source: https://github.com/dotnet/docfx/blob/main/test/docfx.Snapshot.Tests/SamplesTest.SeedMarkdown/BuildFromAssembly.Class1.verified.md A simple method that prints 'Hello World'. ```APIDOC ## HelloWorld() ### Description Hello World. ### Method `public static void HelloWorld()` ``` -------------------------------- ### Custom Build Steps with Plugins Source: https://github.com/dotnet/docfx/blob/main/RELEASENOTE.md Create custom build steps by implementing plugins in a `plugins` folder, referencing `@Microsoft.DocAsCode.EntityModel.Plugins.BaseDocumentBuildStep` for guidance. ```csharp @Microsoft.DocAsCode.EntityModel.Plugins.BaseDocumentBuildStep ``` -------------------------------- ### Nested YAML TOC Example Source: https://github.com/dotnet/docfx/blob/main/docs/docs/table-of-contents.md Demonstrates how to nest one TOC file within another by setting the 'href' of a TOC item to point to another 'toc.yml' file. This allows for modular TOC structures. ```yaml items: - name: Overview href: overview.md - name: Reference href: api/toc.yml ``` ```yaml items: - name: System.String href: system.string.yml - name: System.Float href: system.float.yml ``` -------------------------------- ### Get Contacts Operation Source: https://github.com/dotnet/docfx/blob/main/test/Docfx.Build.RestApi.Tests/TestData/contacts-operations.md This snippet defines the parameters for getting a collection of contacts. OData query parameters can be added to filter, sort, and page the response. ```json { "api": "Contacts", "operation": "get contacts", "showComponents": { "codeGenerator": "true" } } ``` -------------------------------- ### Run Docfx with Default Configuration Source: https://github.com/dotnet/docfx/blob/main/docs/reference/docfx-cli-reference/docfx.md Executes metadata, build, and PDF commands using the default 'docfx.json' configuration file. ```powershell docfx ``` -------------------------------- ### Serve Docfx Website Locally Source: https://github.com/dotnet/docfx/blob/main/docs/index.md Build and serve the docfx website locally for preview. The site will be available at http://localhost:8080. ```bash docfx docfx.json --serve ``` -------------------------------- ### Basic Overwrite Section Example Source: https://github.com/dotnet/docfx/blob/main/docs/tutorial/intro_overwrite_files.md A basic example of an overwrite section in a Markdown file. It uses a YAML header block to define the `uid` and other properties for the model to be overwritten. ```markdown --- uid: microsoft.com/docfx/Contacts some_property: value --- Further description for `microsoft.com/docfx/Contacts` ``` -------------------------------- ### Define Build Steps for RTF Processor Source: https://github.com/dotnet/docfx/blob/main/docs/tutorial/howto_build_your_own_type_of_documentation_with_custom_plug-in.md The BuildSteps property returns an enumerable of build steps. This example shows how to return an empty list, indicating no custom build steps are defined for this processor. ```csharp public IEnumerable BuildSteps => Enumerable.Empty(); ``` -------------------------------- ### Example Request for Contact's Manager Link Source: https://github.com/dotnet/docfx/blob/main/test/Docfx.Build.RestApi.Tests/TestData/contacts-operations.md This example demonstrates how to retrieve a link to a specific contact's manager using the Graph API. It targets the '$links/manager' navigation property of a contact. ```http GET https://graph.windows.net/myorganization/contacts/a2fb3752-08b4-413d-af6f-1d99c4c131d9/$links/manager?api-version=1.6 ``` -------------------------------- ### Issue2623() Source: https://github.com/dotnet/docfx/blob/main/test/docfx.Snapshot.Tests/SamplesTest.SeedMarkdown/BuildFromProject.Class1.verified.md A method with example usage and remarks. ```APIDOC ## Issue2623() ### Description This method demonstrates example usage and provides remarks. ### Method public void Issue2623() ### Examples ```csharp MyClass myClass = new MyClass(); void Update() { myClass.Execute(); } ``` ### Remarks For example: MyClass myClass = new MyClass(); void Update() { myClass.Execute(); } ``` -------------------------------- ### Dog.Name Property Source: https://github.com/dotnet/docfx/blob/main/test/docfx.Snapshot.Tests/SamplesTest.SeedMarkdown/BuildFromProject.Dog.verified.md Gets the name of the dog. ```APIDOC ## Name ### Description Gets the name of the dog. ### Property Value - **Name** (string) - Name of the dog. ``` -------------------------------- ### Dog.Age Property Source: https://github.com/dotnet/docfx/blob/main/test/docfx.Snapshot.Tests/SamplesTest.SeedMarkdown/BuildFromProject.Dog.verified.md Gets the age of the dog. ```APIDOC ## Age ### Description Gets the age of the dog. ### Property Value - **Age** (int) - Age of the dog. ``` -------------------------------- ### Get Contacts Source: https://github.com/dotnet/docfx/blob/main/test/Docfx.Build.RestApi.Tests/TestData/contacts-operations.md Retrieves a collection of organizational contacts. ```APIDOC ## GET /myorganization/contacts ### Description Retrieves a collection of organizational contacts. ### Method GET ### Endpoint /myorganization/contacts ``` -------------------------------- ### DoDad Property Source: https://github.com/dotnet/docfx/blob/main/test/docfx.Snapshot.Tests/SamplesTest.SeedMarkdown/BuildFromProject.Inheritdoc.Issue7484.verified.md Gets a string that could have something. ```APIDOC ## DoDad ### Description A string that could have something. ### Property Value [string](https://learn.microsoft.com/dotnet/api/system.string) ### Remarks None ``` -------------------------------- ### Build docfx project with dotnet run Source: https://github.com/dotnet/docfx/blob/main/samples/extensions/README.md Use this command to build the docfx project when integrating with the Docfx.App package. Ensure you are in the project directory. ```bash dotnet run --project build ``` -------------------------------- ### Dog Age Property Source: https://github.com/dotnet/docfx/blob/main/test/docfx.Snapshot.Tests/SamplesTest.SeedMarkdown/BuildFromProject.Dog.verified.md Gets the age of the dog. ```csharp public int Age { get; } ``` -------------------------------- ### Get a contact's group memberships Source: https://github.com/dotnet/docfx/blob/main/test/Docfx.Build.RestApi.Tests/TestData/contacts-operations.md Retrieves a collection of links to groups that the contact is a direct member of, from the memberOf navigation property. To get all groups (direct and transitive), use the getMemberGroups function. The '$links' segment can be removed to retrieve the full DirectoryObject for each group. ```APIDOC ## Get a contact's group memberships ### Description Gets the contact's group memberships from the **memberOf** navigation property. This property returns only groups that the contact is a direct member of. To get all of the groups that the contact has direct or transitive membership in, call the [getMemberGroups] function. On success, returns a collection of links to the [Group]s that this contact is a member of; otherwise, the response body contains error details. For more information about errors, see [Error Codes and Error Handling]. **Note**: You can remove the "$links" segment from the URL to return the [DirectoryObject]s for the groups instead of links. ### Method GET ### Endpoint /contacts/{contact-id}/$links/memberOf ``` -------------------------------- ### Build Static Site Contents Source: https://github.com/dotnet/docfx/blob/main/docs/reference/docfx-cli-reference/docfx-build.md Generates static site contents using the default docfx.json configuration file. ```pwsh docfx build ``` -------------------------------- ### Configure Build Content and Resources Source: https://github.com/dotnet/docfx/blob/main/docs/reference/docfx-json-reference.md Defines the content files, resource files, and global metadata for the build process. ```json { "build": { "content": ["**/*.{md|yml}"], "resource": ["**/media/**"], "globalMetadata": { "_appTitle": "My App" } } } ``` -------------------------------- ### Issue4017() Source: https://github.com/dotnet/docfx/blob/main/test/docfx.Snapshot.Tests/SamplesTest.SeedMarkdown/BuildFromProject.Class1.verified.md A method with example code for hooking message deleted events. ```APIDOC ## Issue4017() ### Description This method provides an example of how to hook into message deleted events. ### Method public void Issue4017() ### Examples

public void HookMessageDeleted(BaseSocketClient client)
{
    client.MessageDeleted += HandleMessageDelete;
}

public Task HandleMessageDelete(Cacheable<IMessage, ulong> cachedMessage, ISocketMessageChannel channel)
{
    // check if the message exists in cache; if not, we cannot report what was removed
    if (!cachedMessage.HasValue) return;
    var message = cachedMessage.Value;
    Console.WriteLine($"A message ({message.Id}) from {message.Author} was removed from the channel {channel.Name} ({channel.Id}):"
        + Environment.NewLine
        + message.Content);
    return Task.CompletedTask;
}

### Remarks

void Update()
{
    myClass.Execute();
}

``` -------------------------------- ### Basic Build Configuration Source: https://github.com/dotnet/docfx/blob/main/docs/docs/config.md Defines the content and resource files to be included in the site build. Use 'content' for markdown and API YAML files, and 'resource' for static assets like images. ```json { "build": { "content": [ { "files": "**/*.{md,yml}", "exclude": "**/include/**" } ], "resource": [ { "files": "**/images/**" } ] } } ``` -------------------------------- ### Get Contact by ID Source: https://github.com/dotnet/docfx/blob/main/test/Docfx.Build.RestApi.Tests/TestData/contacts-operations.md Retrieves a specific organizational contact by its ID. ```APIDOC ## GET /myorganization/contacts/{id} ### Description Retrieves a specific organizational contact by its ID. ### Method GET ### Endpoint /myorganization/contacts/{id} #### Path Parameters - **id** (string) - Required - The unique identifier of the contact. ``` -------------------------------- ### Get Contact Group Memberships Links Source: https://github.com/dotnet/docfx/blob/main/test/Docfx.Build.RestApi.Tests/TestData/contacts-operations.md Retrieves a collection of links to groups that this contact is a direct member of. To get all groups, use the getMemberGroups function. You can remove the "$links" segment from the URL to return DirectoryObjects for the groups instead of links. This operation is enabled for code generation. ```RESTAPIdocs { "api": "Contacts", "operation": "get contact memberOf links", "showComponents": { "codeGenerator": "true" } } ``` -------------------------------- ### Build with Merged Templates Source: https://github.com/dotnet/docfx/blob/main/docs/tutorial/howto_create_custom_template.md Command to build documentation using both the default and a custom template. This allows leveraging default template features while applying custom modifications. ```bash docfx build docfx.json -t default,c:/docfx_howto/simple_template --serve ``` -------------------------------- ### Get manager link for a contact Source: https://github.com/dotnet/docfx/blob/main/test/Docfx.Build.RestApi.Tests/TestData/contacts-operations.md Returns a link to the specified contact's manager. ```APIDOC ## GET /$links/manager ### Description Returns a link to the specified contact's manager. ### Method GET ### Endpoint https://graph.windows.net/{tenant_id}/contacts/{object_id}/$links/manager?{api_version} ### Parameters #### Path Parameters - **object_id** (GUID) - Required - The object ID of the contact. ### Response #### Success Response (200) - **@odata.id** (string) - A link to the manager resource. ``` -------------------------------- ### Main Method Source: https://github.com/dotnet/docfx/blob/main/test/docfx.Snapshot.Tests/SamplesTest.SeedMarkdown/BuildFromCSharpSourceCode.CSharp.verified.md The entry point of the CSharp application. It accepts an array of strings as arguments. ```APIDOC ## Main(string[]) ```csharp public static void Main(string[] args) ``` ### Parameters `args` [string](https://learn.microsoft.com/dotnet/api/system.string)[] ``` -------------------------------- ### Get Contact MemberOf Links Source: https://github.com/dotnet/docfx/blob/main/test/Docfx.Build.RestApi.Tests/TestData/contacts-operations.md Retrieves the group memberships for a specific organizational contact. ```APIDOC ## GET /myorganization/contacts/{id}/memberOf/$ref ### Description Retrieves the group memberships for a specific organizational contact. ### Method GET ### Endpoint /myorganization/contacts/{id}/memberOf/$ref #### Path Parameters - **id** (string) - Required - The unique identifier of the contact. ``` -------------------------------- ### Generate Initial Docfx Configuration Source: https://github.com/dotnet/docfx/blob/main/docs/reference/docfx-cli-reference/docfx-init.md Use this command to create a default docfx.json file in the current directory. The `--yes` flag automatically answers any prompts. ```powershell docfx init --yes ``` -------------------------------- ### Get Contact Manager Link Source: https://github.com/dotnet/docfx/blob/main/test/Docfx.Build.RestApi.Tests/TestData/contacts-operations.md Retrieves the manager link for a specific organizational contact. ```APIDOC ## GET /myorganization/contacts/{id}/manager/$ref ### Description Retrieves the manager link for a specific organizational contact. ### Method GET ### Endpoint /myorganization/contacts/{id}/manager/$ref #### Path Parameters - **id** (string) - Required - The unique identifier of the contact. ``` -------------------------------- ### Get Contact Member Of Links Source: https://github.com/dotnet/docfx/blob/main/test/Docfx.Build.RestApi.Tests/TestData/overwrite/rest.overwrite.parameters.md Retrieves the links associated with a contact's membership. ```APIDOC ## GET /myorganization/Contacts/1.0/memberOf ### Description Retrieves the links for a contact's membership. ### Method GET ### Endpoint /myorganization/Contacts/1.0/memberOf ### Parameters #### Request Body - **bodyparam** (object) - Required - The new bodyparam description - **location** (string) - Optional - this is overwrite location description - **level** (string) - Optional - this is overwrite level description. Enum: Verbose, Info, Warning ``` -------------------------------- ### DFM Section Syntax Source: https://github.com/dotnet/docfx/blob/main/RELEASENOTE.md Example of using section syntax within Docfx Flavored Markdown (DFM). ```markdown Add section syntax in DFM ``` -------------------------------- ### Get all group memberships (transitive) Source: https://github.com/dotnet/docfx/blob/main/test/Docfx.Build.RestApi.Tests/TestData/contacts-operations.md Retrieves all group memberships for a given user, including transitive memberships. ```APIDOC ## GET /contacts/{contactId}/groupMemberships ### Description Retrieves all group memberships for a given contact, including transitive memberships. ### Method GET ### Endpoint /contacts/{contactId}/groupMemberships ### Parameters #### Path Parameters - **contactId** (string) - Required - The ID of the contact to retrieve group memberships for. ### Response #### Success Response (200) - **value** (array) - A list of group membership objects. - **@odata.nextLink** (string) - URL to retrieve the next page of results, if any. ``` -------------------------------- ### Download Docfx NuGet Package Source: https://github.com/dotnet/docfx/blob/main/docs/index.md This script retrieves the latest nightly build version of Docfx from GitHub Packages, constructs the download URL, and downloads the .nupkg file to the current directory. It requires the GitHub CLI to be authenticated. ```pwsh # Gets Access Token $token = gh auth token # Gets the version of latest nightly build $version = gh api /orgs/dotnet/packages/nuget/docfx/versions --jq '.[0].name' # Gets nupkg download URL. $downloadUrl = "https://nuget.pkg.github.com/dotnet/download/docfx/${version}/${version}.nupkg" # Download nupkg to current directory. Write-Host ('Download nupkg from: {0}' -f $downloadUrl) Invoke-RestMethod -Method Get -Uri $downloadUrl -OutFile "docfx.${version}.nupkg" -Headers @{ Authorization = "Bearer $token" } ``` -------------------------------- ### Get Contact Direct Reports Links Source: https://github.com/dotnet/docfx/blob/main/test/Docfx.Build.RestApi.Tests/TestData/contacts-operations.md Retrieves the direct reports links for a specific organizational contact. ```APIDOC ## GET /myorganization/contacts/{id}/directReports/$ref ### Description Retrieves the direct reports links for a specific organizational contact. ### Method GET ### Endpoint /myorganization/contacts/{id}/directReports/$ref #### Path Parameters - **id** (string) - Required - The unique identifier of the contact. ``` -------------------------------- ### Class1 Class Definition Source: https://github.com/dotnet/docfx/blob/main/test/docfx.Snapshot.Tests/SamplesTest.SeedMarkdown/BuildFromAssembly.Class1.verified.md Defines the basic structure of Class1. This is often the starting point for understanding a class. ```csharp public class Class1 ``` -------------------------------- ### Build with Custom Template Source: https://github.com/dotnet/docfx/blob/main/docs/tutorial/howto_create_custom_template.md Command to build the documentation using a custom template. The `-t` flag specifies the template path. ```bash docfx build docfx.json -t c:/docfx_howto/simple_template --serve ``` -------------------------------- ### Liquid Template Syntax for Partials Source: https://github.com/dotnet/docfx/blob/main/RELEASENOTE.md Demonstrates the Liquid include tag for partials and the custom 'ref' tag for specifying resource file dependencies in templates. ```liquid {% include _partialName %} ``` ```liquid {% ref file1 %} ``` -------------------------------- ### BoolReturningMethod Method Source: https://github.com/dotnet/docfx/blob/main/test/docfx.Snapshot.Tests/SamplesTest.SeedMarkdown/BuildFromProject.Inheritdoc.Issue7484.verified.md A method that accepts a boolean parameter and returns a boolean value. It is used for generating documentation examples. ```csharp public bool BoolReturningMethod(bool source) ``` -------------------------------- ### Capitalized Prefix for Static Readonly Fields and Constants Source: https://github.com/dotnet/docfx/blob/main/samples/seed/articles/csharp_coding_standards.md Start static readonly fields and constants with a capitalized case. ```csharp private static readonly IEntityAccessor EntityAccessor = null; private const string MetadataName = "MetadataName"; ``` -------------------------------- ### System.String Constructor Source: https://github.com/dotnet/docfx/blob/main/test/Docfx.Build.OverwriteDocuments.Tests/TestData/System.String.yml.md This section details the constructors available for the System.String class, including how to instantiate a String object. ```APIDOC ## `System.String.#ctor(System.Char*)` ### Summary Markdown content ``` -------------------------------- ### File Metadata with Glob Patterns Source: https://github.com/dotnet/docfx/blob/main/RELEASENOTE.md Illustrates how to specify different metadata values for files using glob patterns. ```plaintext fileMetadata ``` -------------------------------- ### Dog Constructor Source: https://github.com/dotnet/docfx/blob/main/test/docfx.Snapshot.Tests/SamplesTest.SeedMarkdown/BuildFromProject.Dog.verified.md Initializes a new instance of the Dog class with a name and age. ```csharp public Dog(string name, int age) ``` -------------------------------- ### Enable Post Processors via Command Line Source: https://github.com/dotnet/docfx/blob/main/docs/tutorial/howto_add_a_customized_post_processor.md Alternatively, you can specify post-processors directly on the command line using the `--postProcessors` option, which overrides the `docfx.json` configuration. ```bash docfx build --postProcessors=OutputPDF,BeautifyHTML,OutputPDF ``` -------------------------------- ### GetTailLength Source: https://github.com/dotnet/docfx/blob/main/test/docfx.Snapshot.Tests/SamplesTest.SeedMarkdown/CatLibrary.Cat-2.verified.md An unsafe method to get the cat's tail length. Requires a pointer to an integer for the cat's name. ```APIDOC ## GetTailLength(int*, params object[]) ### Description An unsafe method to get the cat's tail length. Requires a pointer to an integer for the cat's name. ### Method `public long GetTailLength(int* catName, params object[] parameters)` ### Parameters #### Path Parameters - **catName** (int*) - Required - Thie represent for cat name length. - **parameters** (object[]) - Optional - Optional parameters. ### Returns #### Success Response - **long** - Return cat tail's length. ``` -------------------------------- ### Basic Conceptual Template File Source: https://github.com/dotnet/docfx/blob/main/docs/tutorial/howto_create_custom_template.md This file defines how conceptual documents are rendered. Place it in your template folder as `conceptual.html.primary.tmpl`. ```mustache {{{conceptual}}} ``` -------------------------------- ### Export Raw and View Models Source: https://github.com/dotnet/docfx/blob/main/RELEASENOTE.md The `build` subcommand now supports `--exportRawModel` to export the data model and `--exportViewModel` to export the processed view model. ```bash --exportRawModel --exportViewModel ``` -------------------------------- ### Example of a long C# identifier Source: https://github.com/dotnet/docfx/blob/main/docs/spec/metadata_format_spec.md Illustrates a potentially long identifier in C# that might benefit from an alias for easier referencing in Markdown. ```markdown Format(System.IFormatProvider,System.String,System.Object,System.Object) ``` -------------------------------- ### Load Global Metadata Source: https://github.com/dotnet/docfx/blob/main/RELEASENOTE.md Use `--globalMetadata` or `--globalMetadataFile` with the `build` subcommand to load global metadata from the command line or a JSON file. ```bash --globalMetadata, and --globalMetadataFile ``` -------------------------------- ### Dog Constructor Source: https://github.com/dotnet/docfx/blob/main/test/docfx.Snapshot.Tests/SamplesTest.SeedMarkdown/BuildFromProject.Dog.verified.md Initializes a new instance of the Dog class with a name and age. ```APIDOC ## Dog(string name, int age) ### Description Constructor for the Dog class. ### Parameters #### Path Parameters - **name** (string) - Description: Name of the dog. - **age** (int) - Description: Age of the dog. ``` -------------------------------- ### Method Syntax in YAML Source: https://github.com/dotnet/docfx/blob/main/docs/docs/dotnet-yaml-format.md Illustrates the YAML representation for methods, including UIDs, IDs, and C# names. Methods without parameters must end with parentheses in their ID. ```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) ``` -------------------------------- ### HelloWorld Method Source: https://github.com/dotnet/docfx/blob/main/test/docfx.Snapshot.Tests/SamplesTest.SeedMarkdown/BuildFromAssembly.Class1.verified.md A static method named HelloWorld within Class1. It is intended to perform a simple greeting action. ```csharp public static void HelloWorld() ``` -------------------------------- ### Custom Footer with Mustache Source: https://github.com/dotnet/docfx/blob/main/docs/docs/template.md Replace the default footer using a Mustache template partial. This example adds a GitHub Follow button to the footer. ```html ``` -------------------------------- ### Process Output Files with a Custom Post Processor Source: https://github.com/dotnet/docfx/blob/main/docs/tutorial/howto_add_a_customized_post_processor.md Implement the `Process` method to manipulate manifest files and output content within the specified output folder. The `manifest` parameter contains all files to be processed. ```csharp public Manifest Process(Manifest manifest, string outputFolder) { // TODO: add/remove/update all the files included in manifest return manifest; } ``` -------------------------------- ### Markdown Metadata Example Source: https://github.com/dotnet/docfx/blob/main/docs/docs/config.md Applies metadata to a Markdown file using YAML Front Matter. This metadata influences the page's appearance and context. ```md --- title: a title description: a description --- ``` -------------------------------- ### IAnimal Eat Method (No Parameters) Source: https://github.com/dotnet/docfx/blob/main/test/docfx.Snapshot.Tests/SamplesTest.SeedMarkdown/CatLibrary.IAnimal.verified.md Defines the basic Eat method for an animal. ```csharp void Eat() ``` -------------------------------- ### Create Integer Tween Source: https://github.com/dotnet/docfx/blob/main/test/docfx.Snapshot.Tests/SamplesTest.SeedMarkdown/BuildFromProject.Inheritdoc.Issue8101.verified.md Use this method to create a tween for integer values. It requires start and end values, duration, and a callback for value changes. ```csharp public static object Tween(int from, int to, float duration, Action onChange) ``` -------------------------------- ### Create Float Tween Source: https://github.com/dotnet/docfx/blob/main/test/docfx.Snapshot.Tests/SamplesTest.SeedMarkdown/BuildFromProject.Inheritdoc.Issue8101.verified.md Use this method to create a tween for float values. It requires start and end values, duration, and a callback for value changes. ```csharp public static object Tween(float from, float to, float duration, Action onChange) ``` -------------------------------- ### Configure Docfx for Compatibility Source: https://github.com/dotnet/docfx/blob/main/RELEASENOTE.md To maintain the previous behavior of generic type file names and URLs, add the `useCompatibilityFileName` option to the metadata configuration in `docfx.json`. ```json { "metadata": [ { "src": [ { "src": ".", "files": [ "**/*.cs" ] } ], "dest": "api", "useCompatibilityFileName": true } ] } ```