diff --git a/components/TOC.js b/components/TOC.js index 4f6dde5ee514..855ccd422e1e 100644 --- a/components/TOC.js +++ b/components/TOC.js @@ -7,10 +7,11 @@ export default function TOC({ cssBreakingPoint = 'xl', toc, contentSelector, + depth = 2, }) { if (!toc || !toc.length) return null const minLevel = toc.reduce((mLevel, item) => (!mLevel || item.lvl < mLevel) ? item.lvl : mLevel, 0) - const tocItems = toc.filter(item => item.lvl <= minLevel + 2).map(item => ({ ...item, content: item.content.replace(/[\s]?\{\#[\w\d\-_]+\}$/, '').replace(/(<([^>]+)>)/gi, '') })) + const tocItems = toc.filter(item => item.lvl <= minLevel + depth).map(item => ({ ...item, content: item.content.replace(/[\s]?\{\#[\w\d\-_]+\}$/, '').replace(/(<([^>]+)>)/gi, '') })) const [open, setOpen] = useState(false) diff --git a/components/layout/DocsLayout.js b/components/layout/DocsLayout.js index e48c62e92ec9..c8ef60325ac6 100644 --- a/components/layout/DocsLayout.js +++ b/components/layout/DocsLayout.js @@ -94,7 +94,7 @@ export default function DocsLayout({ post, navItems = {}, children }) {

- +
Definitions -#### Application {#definitionsApplication} +#### Application An application is any kind of computer program or a group of them. It MUST be a [producer](#definitionsProducer), a [consumer](#definitionsConsumer) or both. An application MAY be a microservice, IoT device (sensor), mainframe process, etc. An application MAY be written in any number of different programming languages as long as they support the selected [protocol](#definitionsProtocol). An application MUST also use a protocol supported by the server in order to connect and exchange [messages](#definitionsMessage). -#### Producer {#definitionsProducer} +#### Producer A producer is a type of application, connected to a server, that is creating [messages](#definitionsMessage) and addressing them to [channels](#definitionsChannel). A producer MAY be publishing to multiple channels depending on the server, protocol, and use-case pattern. -#### Consumer {#definitionsConsumer} +#### Consumer A consumer is a type of application, connected to a server via a supported [protocol](#definitionsProtocol), that is consuming [messages](#definitionsMessage) from [channels](#definitionsChannel). A consumer MAY be consuming from multiple channels depending on the server, protocol, and the use-case pattern. -#### Message {#definitionsMessage} +#### Message A message is the mechanism by which information is exchanged via a channel between servers and applications. A message MUST contain a payload and MAY also contain headers. The headers MAY be subdivided into [protocol](#definitionsProtocol)-defined headers and header properties defined by the application which can act as supporting metadata. The payload contains the data, defined by the application, which MUST be serialized into a format (JSON, XML, Avro, binary, etc.). Since a message is a generic mechanism, it can support multiple interaction patterns such as event, command, request, or response. -#### Channel {#definitionsChannel} +#### Channel A channel is an addressable component, made available by the server, for the organization of [messages](#definitionsMessage). [Producer](#definitionsProducer) applications send messages to channels and [consumer](#definitionsConsumer) applications consume messages from channels. Servers MAY support many channel instances, allowing messages with different content to be addressed to different channels. Depending on the server implementation, the channel MAY be included in the message via protocol-defined headers. -#### Protocol {#definitionsProtocol} +#### Protocol A protocol is the mechanism (wireline protocol OR API) by which [messages](#definitionsMessage) are exchanged between the application and the [channel](#definitionsChannel). Example protocol include, but are not limited to, AMQP, HTTP, JMS, Kafka, MQTT, STOMP, WebSocket. -## Specification {#specification} +## Specification -### Format {#format} +### Format The files describing the message-driven API in accordance with the AsyncAPI Specification are represented as JSON objects and conform to the JSON standards. YAML, being a superset of JSON, can be used as well to represent a A2S (AsyncAPI Specification) file. @@ -75,7 +77,7 @@ In order to preserve the ability to round-trip between YAML and JSON formats, YA - Tags MUST be limited to those allowed by the [JSON Schema ruleset](http://www.yaml.org/spec/1.2/spec.html#id2803231) - Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset -### File Structure {#file-structure} +### File Structure The A2S representation of the API is made of a single file. However, parts of the definitions can be split into separate files, at the discretion of the user. @@ -83,9 +85,9 @@ This is applicable for `$ref` fields in the specification as follows from the [J By convention, the AsyncAPI Specification (A2S) file is named `asyncapi.json` or `asyncapi.yaml`. -### Schema {#schema} +### Schema -#### AsyncAPI Object {#A2SObject} +#### AsyncAPI Object This is the root document object for the API specification. It combines resource listing and API declaration together into one document. @@ -106,7 +108,7 @@ Field Name | Type | Description This object can be extended with [Specification Extensions](#specificationExtensions). -#### AsyncAPI Version String {#A2SVersionString} +#### AsyncAPI Version String The version string signifies the version of the AsyncAPI Specification that the document complies to. The format for this string _must_ be `major`.`minor`.`patch`. The `patch` _may_ be suffixed by a hyphen and extra alphanumeric characters. @@ -116,7 +118,7 @@ The patch version will not be considered by tooling, making no distinction betwe In subsequent versions of the AsyncAPI Specification, care will be given such that increments of the `minor` version should not interfere with operations of tooling developed to a lower minor version. Thus a hypothetical `1.1.0` specification should be usable with tooling designed for `1.0.0`. -#### Identifier {#A2SIdString} +#### Identifier This field represents a unique universal identifier of the [application](#definitionsApplication) the AsyncAPI document is defining. It must conform to the URI format, according to [RFC3986](http://tools.ietf.org/html/rfc3986). @@ -144,7 +146,7 @@ id: 'urn:com:smartylighting:streetlights:server' id: 'https://github.com/smartylighting/streetlights-server' ``` -#### Info Object {#infoObject} +#### Info Object The object provides metadata about the API. The metadata can be used by the clients if needed. @@ -196,7 +198,7 @@ license: version: 1.0.1 ``` -#### Contact Object {#contactObject} +#### Contact Object Contact information for the exposed API. @@ -226,7 +228,7 @@ url: http://www.example.com/support email: support@example.com ``` -#### License Object {#licenseObject} +#### License Object License information for the exposed API. @@ -253,7 +255,7 @@ name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html ``` -#### Servers Object {#serversObject} +#### Servers Object The Servers Object is a map of [Server Objects](#serverObject). @@ -285,7 +287,7 @@ production: ``` -#### Server Object {#serverObject} +#### Server Object An object representing a message broker, a server or any other kind of computer program capable of sending and/or receiving data. This object is used to capture details such as URIs, protocols and security configuration. Variable substitution can be used so that some details, for example usernames and passwords, can be injected by code generation tools. @@ -420,7 +422,7 @@ servers: ``` -#### Server Variable Object {#serverVariableObject} +#### Server Variable Object An object representing a Server Variable for server URL template substitution. @@ -439,7 +441,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens -#### Default Content Type {#defaultContentTypeString} +#### Default Content Type A string representing the default content type to use when encoding/decoding a message's payload. The value MUST be a specific media type (e.g. `application/json`). This value MUST be used by schema parsers when the [contentType](#messageObjectContentType) property is omitted. @@ -462,7 +464,7 @@ defaultContentType: application/json -#### Channels Object {#channelsObject} +#### Channels Object Holds the relative paths to the individual channel and their operations. Channel paths are relative to servers. @@ -495,7 +497,7 @@ user/signedup: -#### Channel Item Object {#channelItemObject} +#### Channel Item Object Describes the operations available on a single channel. @@ -593,7 +595,7 @@ subscribe: -#### Operation Object {#operationObject} +#### Operation Object Describes a publish or a subscribe operation. This provides a place to document how and why messages are sent and received. For example, an operation might describe a chat application use case where a user sends a text message to a group. @@ -689,7 +691,7 @@ traits: -#### Operation Trait Object {#operationTraitObject} +#### Operation Trait Object Describes a trait that MAY be applied to an [Operation Object](#operationObject). This object MAY contain any property from the [Operation Object](#operationObject), except `message` and `traits`. @@ -729,7 +731,7 @@ bindings: -#### Parameters Object {#parametersObject} +#### Parameters Object Describes a map of parameters included in a channel name. @@ -776,7 +778,7 @@ user/{userId}/signup: -#### Parameter Object {#parameterObject} +#### Parameter Object Describes a parameter included in a channel name. @@ -826,7 +828,7 @@ user/{userId}/signup: -#### Server Bindings Object {#serverBindingsObject} +#### Server Bindings Object Map describing protocol-specific definitions for a server. @@ -851,7 +853,7 @@ Field Name | Type | Description -#### Channel Bindings Object {#channelBindingsObject} +#### Channel Bindings Object Map describing protocol-specific definitions for a channel. @@ -876,7 +878,7 @@ Field Name | Type | Description -#### Operation Bindings Object {#operationBindingsObject} +#### Operation Bindings Object Map describing protocol-specific definitions for an operation. @@ -903,7 +905,7 @@ Field Name | Type | Description -#### Message Bindings Object {#messageBindingsObject} +#### Message Bindings Object Map describing protocol-specific definitions for a message. @@ -933,7 +935,7 @@ Field Name | Type | Description -#### Message Object {#messageObject} +#### Message Object Describes a message received on a given channel and operation. @@ -958,7 +960,7 @@ Field Name | Type | Description This object can be extended with [Specification Extensions](#specificationExtensions). -##### Schema formats table {#messageObjectSchemaFormatTable} +##### Schema formats table The following table contains a set of values that every implementation MUST support. @@ -1091,7 +1093,7 @@ payload: -#### Message Trait Object {#messageTraitObject} +#### Message Trait Object Describes a trait that MAY be applied to a [Message Object](#messageObject). This object MAY contain any property from the [Message Object](#messageObject), except `payload` and `traits`. @@ -1130,11 +1132,11 @@ schemaFormat: 'application/vnd.apache.avro+yaml;version=1.9.0' contentType: application/json ``` -#### Tags Object {#tagsObject} +#### Tags Object A Tags object is a list of Tag Objects. -#### Tag Object {#tagObject} +#### Tag Object Allows adding meta data to a single tag. @@ -1167,7 +1169,7 @@ description: User-related messages -#### External Documentation Object {#externalDocumentationObject} +#### External Documentation Object Allows referencing an external resource for extended documentation. @@ -1194,7 +1196,7 @@ description: Find more info here url: https://example.com ``` -#### Reference Object {#referenceObject} +#### Reference Object A simple object to allow referencing other components in the specification, internally and externally. @@ -1222,7 +1224,7 @@ This object cannot be extended with additional properties and any properties add $ref: '#/components/schemas/Pet' ``` -#### Components Object {#componentsObject} +#### Components Object Holds a set of reusable objects for different aspects of the AsyncAPI specification. All objects defined within the components object will have no effect on the API unless they are explicitly referenced from properties outside the components object. @@ -1415,7 +1417,7 @@ components: maximum: 100 ``` -#### Schema Object {#schemaObject} +#### Schema Object The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. @@ -1481,7 +1483,7 @@ Field Name | Type | Description This object can be extended with [Specification Extensions](#specificationExtensions). -###### Composition and Inheritance (Polymorphism) {#schemaComposition} +###### Composition and Inheritance (Polymorphism) The AsyncAPI Specification allows combining and extending model definitions using the `allOf` property of JSON Schema, in effect offering model composition. `allOf` takes in an array of object definitions that are validated *independently* but together compose a single object. @@ -1815,7 +1817,7 @@ schemas: -#### Security Scheme Object {#securitySchemeObject} +#### Security Scheme Object Defines a security scheme that can be used by the operations. Supported schemes are: @@ -1967,7 +1969,7 @@ flows: read:pets: read your pets ``` -#### OAuth Flows Object {#oauthFlowsObject} +#### OAuth Flows Object Allows configuration of the supported OAuth Flows. @@ -1981,7 +1983,7 @@ Field Name | Type | Description This object MAY be extended with [Specification Extensions](#specificationExtensions). -#### OAuth Flow Object {#oauthFlowObject} +#### OAuth Flow Object Configuration details for a supported OAuth Flow @@ -2036,7 +2038,7 @@ flows: read:pets: read your pets ``` -#### Security Requirement Object {#securityRequirementObject} +#### Security Requirement Object Lists the required security schemes to execute this operation. The name used for each property MUST correspond to a security scheme declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). @@ -2092,7 +2094,7 @@ petstore_auth: - read:pets ``` -### Correlation ID Object {#correlationIdObject} +### Correlation ID Object An object that specifies an identifier at design time that can used for message tracing and correlation. @@ -2121,7 +2123,7 @@ description: Default Correlation ID location: $message.header#/correlationId ``` -### Runtime Expression {#runtimeExpression} +### Runtime Expression A runtime expression allows values to be defined based on information that will be available within the message. This mechanism is used by [Correlation ID Object](#correlationIdObject). @@ -2138,7 +2140,7 @@ The runtime expression is defined by the following [ABNF](https://tools.ietf.org The table below provides examples of runtime expressions and examples of their use in a value: -##### Examples {#runtimeExpressionExamples} +##### Examples Source Location | Example expression | Notes ---|:---|:---| @@ -2147,7 +2149,7 @@ Message Payload Property | `$message.payload#/messageId` | Correlation ID is set Runtime expressions preserve the type of the referenced value. -### Specification Extensions {#specificationExtensions} +### Specification Extensions While the AsyncAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points. @@ -2159,7 +2161,7 @@ Field Pattern | Type | Description The extensions may or may not be supported by the available tooling, but those may be extended as well to add requested support (if tools are internal or open-sourced). -### Data Type Formats {#dataTypeFormat} +### Data Type Formats Primitives have an optional modifier property: `format`. The AsyncAPI specification uses several known formats to more finely define the data type being used. diff --git a/scripts/build-post-list.js b/scripts/build-post-list.js index 1d52ce96254e..aa98c26dbcf8 100644 --- a/scripts/build-post-list.js +++ b/scripts/build-post-list.js @@ -88,8 +88,15 @@ function walkDirectories(directories, result, sectionWeight = 0, sectionTitle) { function slugifyToC(str) { let slug + // Try to match heading ids like {# myHeadingId} const headingIdMatch = str.match(/[\s]?\{\#([\w\d\-_]+)\}/) - if (headingIdMatch && headingIdMatch.length >= 2) slug = headingIdMatch[1] + if (headingIdMatch && headingIdMatch.length >= 2) { + slug = headingIdMatch[1] + } else { + // Try to match heading ids like {} + const anchorTagMatch = str.match(/[\s]*= 2) slug = anchorTagMatch[1] + } return slug || slugify(str, { firsth1: true, maxdepth: 6 }) }