API Page
The API page is a YAML file format designed to represent general API pages in a structured manner. It provides a diverse set of UX components commonly found in API pages, such as headings, markdown content, fact sheets, parameters, lists, inheritance chains, and code blocks:
#YamlMime:ApiPage
title: System.String
languageId: csharp
body:
- h1: String Class
- facts:
- name: Assembly
value: System.Runtime.dll
- markdown: Represents text as a sequence of UTF-16 code units.
- code: public sealed class String
The first line of the YAML file MUST be #YamlMime:ApiPage, followed by structured data that adheres to the following form:
/** Represents a general API page */
type ApiPage = {
/** Page title */
title: string;
/** Opaque metadata about the page as HTML \<meta> tags */
metadata?: { [key: string]: string | string[] };
/** Default code [language identifier](https://code.visualstudio.com/docs/languages/identifiers#_known-language-identifiers) */
languageId?: string;
/** Page body */
body: Block[];
};
Inline Elements
An inline can be a string, a link, or a mix of both:
/** Represents an inline composed of text or links */
type Span = string | { text: string; url?: string };
type Inline = Span | Span[];
Example:
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
This will be rendered as:
-
a stringa mix of string andlink
Block Elements
The body of the API page consists of an array of block level elements, each representing a different component of the page. The various types of blocks are explained below:
Markdown
Represents a markdown block with the markdown property for markdown content.
/** Represents a markdown block */
type Markdown = {
/** Markdown content */
markdown: markdown;
};
Example:
body:
- markdown: |
This is a **markdown** block with [links](https://dotnet.github.io/docfx).
This will be rendered as:
This is a markdown block with links.
Code
Represents a code block. It includes the code property for the code text and an optional languageId for the code language identifier.
/** Represents a code block */
type Code = {
/** Code text */
code: string;
/** Code [language identifier](https://code.visualstudio.com/docs/languages/identifiers#_known-language-identifiers) */
languageId?: string;
};
Example:
body:
- code: public class System.String {}
This will be rendered as:
public class System.String {}Heading
Represents a heading in the API page. Each heading is defined by its level (from h1 to h6) and an optional identifier id for URL fragments.
/** Represents a heading */
type Heading =
| { /** Heading title */ h1: string; /** URL fragment */ id?: string }
| { /** Heading title */ h2: string; /** URL fragment */ id?: string }
| { /** Heading title */ h3: string; /** URL fragment */ id?: string }
| { /** Heading title */ h4: string; /** URL fragment */ id?: string }
| { /** Heading title */ h5: string; /** URL fragment */ id?: string }
| { /** Heading title */ h6: string; /** URL fragment */ id?: string };
Example:
body:
- h4: This is an H4
This will be rendered as:
This is an H4
API Heading
Represents an API heading. It includes the API name, an optional URL fragment, and optional flags for deprecation and experimental status.
/** Represents an API heading */
type Api = (
| { /** API name */ api1: string }
| { /** API name */ api2: string }
| { /** API name */ api3: string }
| { /** API name */ api4: string }
) & {
/** API URL fragment */
id?: string;
/** Is this API deprecated, or the deprecation reason in markdown format */
deprecated?: boolean | string;
/** Is this API experimental, or the preview disclaimer text */
preview?: boolean | string;
/** API source URL */
src?: string;
/** Opaque metadata about the API as HTML data-{key} attributes */
metadata?: { [key: string]: string };
};
Example:
body:
- api4: Foo(int bar)
deprecated: true
src: https://dotnet.github.io/docfx
This will be rendered as:
Foo(int bar) Deprecated
Example:
body:
- api4: Foo(int baz)
preview: true
src: https://dotnet.github.io/docfx
This will be rendered as:
Foo(int baz) Preview
Facts
Represents a sheet of facts, each consisting of a name and a value.
/** Represents a sheet of facts */
type Facts = {
facts: {
name: string;
value: Inline;
}[];
};
Example:
body:
- facts:
- name: Namespace
value:
- text: System.Runtime
url: https://learn.microsoft.com/dotnet/api/system.runtime
- name: Assembly
value: System.Runtime.dll
This will be rendered as:
- Namespace
- System.Runtime
- Assembly
- System.Runtime.dll
List
Represents a list of content.
/** Represents a list of content */
type List = {
list: Inline[];
};
Example:
body:
- list:
- text: object
url: https://learn.microsoft.com/dotnet/api/system.object
- text: string
url: https://learn.microsoft.com/dotnet/api/system.string
This will be rendered as:
Inheritance
Represents a single inheritance chain from base type to derived type.
/** Represents a single inheritance chain from base type to derived type */
type Inheritance = {
inheritance: Inline[];
};
Example:
body:
- inheritance:
- text: object
url: https://learn.microsoft.com/dotnet/api/system.object
- text: string
url: https://learn.microsoft.com/dotnet/api/system.string
This will be rendered as:
Parameters
Represents a set of parameters.
type Param = {
/** Parameter name */
name?: string;
/** Parameter type */
type?: Inline;
/** Parameter default value */
default?: string;
/** Parameter description in markdown format */
description?: markdown;
/** Is this parameter deprecated, or the deprecation reason */
deprecated?: boolean | string;
/** Is this parameter experimental, or the preview disclaimer text */
preview?: boolean | string;
}
/** Represents a set of parameters */
type Params = {
parameters: Param[];
};
Example:
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
This will be rendered as:
T-
A generic type.
state = newstring Preview-
The operation status.
removedboolean Deprecated