DocsMD React Components

This repository contains React components used with Speakeasy's Docs product. We provide these components under an open source license, and are provided as a reference for customers that wish to implement custom components.

Component Philosophy

A core philosophy of DocsMD is that any meaningful content should always be rendered inside of MDX, not as properties to a component. This way, search indexers and the like can index the content properly, and any styling that a site may provide for markdown will be applied. These behaviors usually don't happen when content is not present as markdown.

This presents some unique constraints when designing components. Notably, we can't do this:

<MyCustomHeading title="My Heading" />

In this case, anything the markdown parser does to stylize headings, such as adding a copy-link icon, will ignore this heading. That means we must instead write this as:

<MyCustomHeading>

### My Heading

</MyCustomHeading>

So if you're wondering why our components don't follow standard React component conventions, this is why. Most notably, we see this pattern with slots, described below.

Slots

Many DocsMD components take in a heterogenous set of children that need to be "assembled" into a specific structure. For example, the TabbedSection component takes in a set of children that are one of:

• A single SectionTitle component that contains the title, aka the "Responses" heading, with slot="title"
• A set of SectionTab components that contains the contents of each tab, aka the status code, with slot="tab"
• A set of SectionContent components that contains the contents of each section, aka the response body, with slot="section"

Each section tab is correlated with a section component by way of "id". Admittedly we're abusing the concept of an id here, and for historical reasons the actual id on a DOM nodes comes from the headingId property (we have a task to fix that some day).

To support sorting of this "grab bag" of children, we borrow a concept from web components: slots. Each child is assigned a "slot" that is used to determine its position in the final output.

There are two hooks that are used to get components assigned to slots:

• useUniqueChild: gets exactly one child with the given slot, and errors if there are no children with that slot or if there are multiple children with that slot.
• useChildren: gets all children with the given slot, returned as an array

It's a little convoluted, and slightly hacky in the React world, but has proven powerful so far.

Component-Specific Documentation

See the source code for each component in the src/components directory for documentation each component. Property types are always defined in a file called types.ts, and includes documentation for each property.