What is Markdoc?
Markdoc is a lightweight, flexible, and powerful Markdown-based syntax for content authoring and documentation. It was developed by Stripe, initially for internal use, before being released as an open-source tool. Markdoc extends the traditional Markdown format with additional features, such as variables, conditional logic, and reusable components. This extended functionality makes it particularly well-suited for creating interactive and dynamic documentation.
Visualizing What's Possible
Each API Portal comes with its own Kitchen Sink.
Append /kitchen_sink to your base portal path to see the kitchen sink. e.g. https://demo.apiable.io/kitchen_sink
Here, you'll see all of the components Apiable provides, along with a sandbox to try things out.
Markdoc documentation
Key features of Markdoc include the use of Variables and Custom Components.
Variables
Markdoc supports the use of variables and conditional logic within documents. This makes content more dynamic and adaptable based on certain conditions or user inputs.
We currently support all of the following variables:
Variable Name | Description | Type |
isAuthenticated | Is the user logged in | Boolean |
heroText1 | Text set from theming | String |
heroText2 | Text set from theming | String |
ctaButton1 | Text set from theming | String |
ctaButton2 | Text set from theming | String |
heroDescription1 | Text set from theming | String |
heroDescription2 | Text set from theming | String |
showVideo | Boolean set from theming | Boolean |
videoUrl | Embedded video url set from theming | String |
VideoText | Text set from theming | String |
productText1 | Text set from theming | String |
productText2 | Text set from theming | String |
productsLink | Text set from theming, e.g “Show all products” | String |
heroImage | Link to an image, set from theming | String |
Components
Markdoc allows the creation of custom tags and components, enabling users to extend Markdown with reusable and interactive elements. This feature is particularly useful for technical documentation that requires dynamic content.
We currently support all of the following components:
RoundedButton
Button renders a rounded button and takes target, variant, and rounded(optional) parameters.
Valid options for variant are primary and secondary
Valid values for rounded are true and false
{% roundedButton target="/products" variant="primary" rounded=false %} Products {% /roundedButton %}Callout
{% callout title="check" %} Markdoc is open-source—check out its [source](<http://github.com/markdoc/markdoc>) to see how it works. {% /callout %}CTA
{% cta title=$heroText1 title2=$heroText2 /%}Fence (code-block)
```javascript /** @type {import('@tailwindlabs/lorem').ipsum} */ export default { lorem: 'ipsum', dolor: ['sit', 'amet', 'consectetur'], adipiscing: { elit: true, }, }Frame
## Frame ```tsx {% frame %} {% verticalSpacer height="2rem" /%} {% productCard slug="bike-insurance-affiliate-api" /%} [{% $productsLink %}](/products) {% .alignCenter .text-sm %} {% /frame %}Grid
{% grid %} {% if $isAuthenticated %} {% productCard slug="bike-insurance-affiliate-api" /%} {% productCard slug="bike-insurance-pricing-api2" /%} {% /if %} {% productCard slug="astronomy-picture-of-the-day" /%} {% /grid %}Iframe
{% iframe src=$videoUrl padding="0rem 8rem 0rem 8rem" %} {% smalltext textAlign="center" maxWidth="175ch" lineHeight="200%" %} {% $videoText%} {% /smalltext %} {% /iframe %}ProductCard
{% productCard slug="astronomy-picture-of-the-day" /%}ProductCards
Component that automatically pulls numberOfProducts products and displays them in a grid.
By default, if the numberOfProducts parameter is not set, the value will be 2.
{% productCards numberOfProducts=2 /%}ProductFeatures
{% productFeatures /%}ProductDocumentation
{% productDocumentation /%}ProductPlanTable
{% productPlanTable /%}SideBySide
{% sidebyside %} {% roundedButton target="/products" variant="primary" %} {% $ctaButton1 %} {% /roundedButton %} {% roundedButton target="/documentation" variant="secondary" %} {% $ctaButton2 %} {% /roundedButton %} {% /sidebyside %}SmallText
{% smalltext textAlign="center" maxWidth="175ch" lineHeight="200%" %} {% $videoText%} {% /smalltext %}Tabs
{% tabs %} {% tab label="Details" %} {% productFeatures /%} {% /tab %} {% tab label="Plans" %} {% productPlanTable /%} {% /tab %} {% tab label="Documentation" %} {% productDocumentation /%} {% /tab %} {% /tabs %}VerticalSpacer
Vertical spacer provides vertical empty space between elements. It takes height as attribute. The height can be specified in multiple ways. For example “2rem”, “10px” or “42%”
Newline
Newline inserts a line break between elements. It can be used to separate content with a single or multiple line breaks.
For instance, to insert a single newline, use {% newline /%}. You can also stack multiple newline tags to add extra space.
Resource
The Resource component displays a card with information about a resource, such as an article or news update. It includes attributes like title, subtitle, description, image, and link. Labels can be used to categorize the resource, for example, labels=["NEWS"]. You can also choose different display styles using the view attribute, such as "list" for a compact layout. Example usage:
{% resource title="Example title" subtitle="example subtitle" description="Example description" image="image url" link="the link to the news page" labels=["NEWS"] view="list" /%}Do you require additional components for your portal?
There are two options:
Build your own component and publish it on your portal.
Ask us to build a component for you.
Reach out to us at support@apiable.io for further information.