Run this command to install the Markdoc library:
``` -------------------------------- ### Markdoc Content Example Source: https://context7.com/markdoc/docs/llms.txt Example of a Markdoc file demonstrating the use of frontmatter, custom tags like 'callout', and links. ```markdown --- title: Getting Started description: Install and use Markdoc --- # {% $markdoc.frontmatter.title %} {% callout type="note" %} Run `npm install @markdoc/markdoc` to get started. {% /callout %} {% link href="/docs/syntax" %}Learn the syntax{% /link %} ``` -------------------------------- ### Example HTML Output Source: https://github.com/markdoc/docs/blob/main/pages/docs/render.md An example of the HTML output generated by Markdoc's HTML renderer. ```htmlRun this command to install the Markdoc library:
``` -------------------------------- ### Project Structure with Markdoc Schema Source: https://github.com/markdoc/docs/blob/main/pages/docs/nextjs.md Example project structure showing the location of the Markdoc schema directory. ```directory . ├── components │ ├── ... │ └── Link.js ├── markdoc │ ├── functions.js │ ├── nodes │ │ ├── ... │ │ ├── link.markdoc.js │ │ └── index.js │ └── tags │ ├── ... │ └── index.js ├── pages │ ├── _app.js │ └── index.md └── next.config.js ``` -------------------------------- ### JSON Frontmatter Example Source: https://github.com/markdoc/docs/blob/main/pages/docs/frontmatter.md Example of frontmatter structured using JSON syntax. This is a common choice for data interchange. ```json --- { "title": "Authoring in Markdown", "description": "Quickly author amazing content with Markdoc syntax, a superset of Markdown.", "date": "2022-04-01" } --- ``` -------------------------------- ### GraphQL Frontmatter Example Source: https://github.com/markdoc/docs/blob/main/pages/docs/frontmatter.md Example of frontmatter structured using GraphQL syntax. This can be useful if your content is managed via a GraphQL API. ```graphql --- { page { title description date } } --- ``` -------------------------------- ### Full Attribute Example Source: https://github.com/markdoc/docs/blob/main/spec/index.md Demonstrates the syntax for a full attribute with a string and an array value. ```markdoc {% foo="bar" baz=[1, 2, 3] %} ``` -------------------------------- ### YAML Frontmatter Example Source: https://github.com/markdoc/docs/blob/main/pages/docs/frontmatter.md Example of frontmatter structured using YAML syntax. This is commonly used for page-level metadata. ```yaml --- title: Authoring in Markdoc description: Quickly author amazing content with Markdoc syntax, a superset of Markdown. date: 2022-04-01 --- ``` -------------------------------- ### Example Markdoc File Structure Source: https://github.com/markdoc/docs/blob/main/pages/docs/nextjs.md Illustrates where to place your Markdoc files within a Next.js project structure. ```directory pages ├── _app.js ├── docs │ └── getting-started.md └── index.md ``` -------------------------------- ### TOML Frontmatter Example Source: https://github.com/markdoc/docs/blob/main/pages/docs/frontmatter.md Example of frontmatter structured using TOML syntax. This format is another option for page-level metadata. ```toml --- title = "Authoring in Markdoc" description = "Quickly author amazing content with Markdoc syntax, a superset of Markdown." date = "2022-04-01" --- ``` -------------------------------- ### Basic Markdoc Content Source: https://github.com/markdoc/docs/blob/main/pages/docs/nextjs.md Example of a Markdoc file with frontmatter and basic Markdown content. ```markdown --- title: Get started with Markdoc description: How to get started with Markdoc --- # Get started with Markdoc ``` -------------------------------- ### Example JSON Renderable Tree Node Source: https://github.com/markdoc/docs/blob/main/pages/docs/render.md An example structure of a Markdoc renderable tree node, representing content ready for rendering. ```json { "name": "article", "attributes": {}, "children": [ { "name": "h1", "attributes": {}, "children": ["Header"], "$$mdtag": true } ], "$$mdtag": true } ``` -------------------------------- ### Example JSON AST Node Source: https://github.com/markdoc/docs/blob/main/pages/docs/render.md An example structure of a Markdoc Abstract Syntax Tree (AST) node, representing parsed content. ```json { "type": "document", "attributes": {}, "children": [ { "type": "paragraph", "attributes": {}, "children": [...], "lines": [0, 2], "location": { "start": { "line": 0 }, "end": { "line": 2 } }, "errors": [], "inline": false, } ], "lines": [], "errors": [], "inline": false } ``` -------------------------------- ### Assemble Config and Render Markdown with Custom Tags Source: https://context7.com/markdoc/docs/llms.txt Assemble the Markdoc configuration with custom tags and then parse, transform, and render Markdown content that utilizes these custom tags. This example demonstrates rendering a 'callout' and a 'button' tag. ```javascript // Assemble config and render import Markdoc from '@markdoc/markdoc'; import { callout } from './schema/Callout.markdoc'; import { button } from './schema/Button.markdoc'; const config = { tags: { callout, button } }; const doc = ` {% callout type="warning" title="Important" %} Back up your data before proceeding. {% /callout %} {% button href="/docs/next-steps" label="Continue" variant="primary" /%} `; const ast = Markdoc.parse(doc); const content = Markdoc.transform(ast, config); const html = Markdoc.renderers.html(content); ``` -------------------------------- ### Basic AST Validation Example Source: https://github.com/markdoc/docs/blob/main/pages/docs/validation.md Parse a Markdoc document and then validate its AST. The `errors` array will contain any syntax issues found. ```javascript const doc = `# Heading`; const ast = Markdoc.parse(doc); const errors = Markdoc.validate(ast, config); // Do something with the errors ``` -------------------------------- ### Built-in Markdoc Tags Example Source: https://context7.com/markdoc/docs/llms.txt Demonstrates the usage of built-in Markdoc tags for conditionals, rich tables with colspan, and partial content inclusion with scoped variables. ```markdown {% comment %} --- Conditionals --- {% /comment %} {% if and($user.loggedIn, equals($user.plan, "pro")) %} Welcome back, {% $user.name %}! You have **Pro** access. {% else $user.loggedIn /%} Upgrade to Pro to unlock all features. {% else /%} Please log in to continue. {% /if %} {% comment %} --- Rich table with colspan and code --- {% /comment %} {% table %} * Function {% width="30%" %} * Returns {% width="20%" %} * Example {% width="50%" %} --- * `equals` * `boolean` * ``` equals($plan, "pro") => true ``` --- * `default` * `mixed` * `default($name, "Anonymous")` --- * Two columns {% colspan=2 %} * Single remaining cell {% /table %} {% comment %} --- Partials with scoped variables --- {% /comment %} {% partial file="sdk-install.md" variables={sdk: "Python", version: "3.11"} /%} ``` -------------------------------- ### Built-in Markdoc Functions Example Source: https://context7.com/markdoc/docs/llms.txt Illustrates the use of built-in Markdoc functions for strict equality checks, boolean logic (and, or, not), providing default values, and debugging variables. ```markdown {% comment %} equals — strict equality {% /comment %} {% if equals($theme, "dark") %} Dark mode is active. {% /if %} {% comment %} and / or / not — boolean logic {% /comment %} {% if and(not($maintenance), or($user.admin, $user.beta)) %} Feature is accessible. {% /if %} {% comment %} default — fallback for undefined variables {% /comment %} Welcome, {% default($user.displayName, "Guest") %}! {% comment %} debug — inspect variable values during development {% /comment %} {% debug($config) %} ``` -------------------------------- ### Simple JavaScript Variable Declaration Source: https://github.com/markdoc/docs/blob/main/examples/html-nodejs/content/home.md A basic example of declaring a string variable in JavaScript. ```javascript const x = 'test'; ``` -------------------------------- ### Configure Markdoc with Custom Tags Source: https://github.com/markdoc/docs/blob/main/pages/docs/tags.md Pass your custom tag definitions to the Markdoc `config` object. This example shows how to include the 'callout' tag definition. ```javascript import { callout } from './schema/Callout.markdoc'; import * as components from './components'; /** @type {import('@markdoc/markdoc').Config} */ const config = { tags: { callout } }; const doc = ` # My first custom tag `; const ast = Markdoc.parse(doc); const content = Markdoc.transform(ast, config); const children = Markdoc.renderers.react(content, React, { components }); ``` -------------------------------- ### Register Custom Functions in Markdoc Source: https://github.com/markdoc/docs/blob/main/pages/docs/nextjs.md Define custom functions for Markdoc by creating a `/markdoc/functions.js` file. This example shows how to create an `upper` function that converts its first parameter to uppercase. ```javascript // markdoc/functions.js export const upper = { transform(parameters) { const string = parameters[0]; return typeof string === 'string' ? string.toUpperCase() : string; } }; ``` -------------------------------- ### Configure Custom Nodes Source: https://github.com/markdoc/docs/blob/main/pages/docs/nodes.md Pass custom nodes to the `config` object to customize Markdoc's rendering. This example shows how to configure a custom `heading` node. ```javascript import { heading } from './schema/Heading.markdoc'; import * as components from './components'; /** @type {import('@markdoc/markdoc').Config} */ const config = { nodes: { heading } }; const ast = Markdoc.parse(doc); const content = Markdoc.transform(ast, config); const children = Markdoc.renderers.react(content, React, { components }); ``` -------------------------------- ### Prism.js Syntax Highlighting with Custom Fence Node Source: https://github.com/markdoc/docs/blob/main/pages/docs/examples/index.md Integrates Prism.js for syntax highlighting in code blocks by creating a custom 'Fence' node. This example shows how to use the 'react-prism' component and configure Markdoc to use this custom node. ```javascript // [Source example](https://github.com/markdoc/docs/blob/main/components/Code.js) import 'prismjs'; import 'prismjs/themes/prism.css'; import Prism from 'react-prism'; export function Fence({ children, language }) { return (Run npm install.
``` -------------------------------- ### Register Built-in Next.js Markdoc Tags Source: https://github.com/markdoc/docs/blob/main/pages/docs/nextjs.md Include built-in Next.js Markdoc tags by exporting them from your schema directory (e.g., `/markdoc/`). This example shows exporting specific tags or all tags from `@markdoc/next.js/tags`. ```javascript // markdoc/tags/Next.markdoc.js export { comment, head, link, script } from '@markdoc/next.js/tags'; // or export * from '@markdoc/next.js/tags'; ``` -------------------------------- ### Build Command Source: https://github.com/markdoc/docs/blob/main/pages/docs/examples/html.md Command to build the project, typically used to compile assets and prepare the application for deployment. ```shell npm run build ``` -------------------------------- ### Interpolating a Variable Source: https://github.com/markdoc/docs/blob/main/spec/index.md Example of inserting a Markdoc variable into the document text. ```markdoc Hello {% $username %} ``` -------------------------------- ### Use Markdoc to parse, transform, and render content Source: https://github.com/markdoc/docs/blob/main/pages/docs/getting-started.md Demonstrates the basic workflow of parsing Markdown-like source, transforming it with configuration, and rendering it to HTML. ```javascript const source = '# Markdoc'; const ast = Markdoc.parse(source); // prettier-ignore const content = Markdoc.transform(ast, /* [config](/docs/config) */); const html = Markdoc.renderers.html(content); ``` -------------------------------- ### Equivalent Full Attributes for Shorthand Source: https://github.com/markdoc/docs/blob/main/spec/index.md Illustrates the equivalent full attribute syntax for the shorthand ID and class attributes. ```markdoc {% id="foo" class="bar" %} ``` -------------------------------- ### Configure Markdoc Mode Source: https://github.com/markdoc/docs/blob/main/pages/docs/nextjs.md Set the `mode` option in `withMarkdoc` to 'static' for pre-rendering pages at build time using `getStaticProps`. ```javascript module.exports = withMarkdoc({ mode: 'static' })({ pageExtensions: // [...](https://nextjs.org/docs/api-reference/next.config.js/custom-page-extensions) }); ``` -------------------------------- ### Table Without Headings Source: https://github.com/markdoc/docs/blob/main/pages/docs/tags.md Example of a Markdoc table structure without explicit headings, using '---' to separate content rows. ```markdown {% table %} --- * foo * bar --- * foo * bar {% /table %} ``` -------------------------------- ### Define Custom Tag: Kebab Case Source: https://github.com/markdoc/docs/blob/main/pages/docs/nextjs.md Example of exporting a default object in `markdoc/tags.js` to define a custom tag with a kebab-case name, 'special-button'. ```javascript // markdoc/tags.js export default { 'special-button': { render: SpecialButton, attributes: { href: { type: String } } } }; ``` -------------------------------- ### Block-level Tag Parsing Source: https://github.com/markdoc/docs/blob/main/public/spec.html A tag is parsed as block-level when its opening and closing markers are on lines by themselves. This example shows 'foo' as a block-level tag containing a paragraph. ```markdoc {% foo %} This is content inside of a block-level tag {% /foo %} ``` -------------------------------- ### Using Variables in Markdoc Source: https://context7.com/markdoc/docs/llms.txt Demonstrates how to use variables within Markdoc documents for dynamic content rendering. Ensure variables are defined in the Markdoc configuration. ```javascript import Markdoc from '@markdoc/markdoc'; const doc = `Hello, {% $user.name %}! You have access to the beta program. {% /if %} {% if equals($user.plan, "enterprise") %} Enterprise support: {% $support.email %} {% /if %} Your SDK version: {% $sdk.version %} `; /** @type {import('@markdoc/markdoc').Config} */ const config = { variables: { flags: { showBeta: true }, user: { name: 'Dr. Mark', plan: 'enterprise' }, support: { email: 'enterprise@example.com' }, sdk: { version: '2.4.1' } } }; const ast = Markdoc.parse(doc); const content = Markdoc.transform(ast, config); const html = Markdoc.renderers.html(content); ``` -------------------------------- ### Configure Next.js with Markdoc Source: https://context7.com/markdoc/docs/llms.txt Configure the next.config.js file to enable Markdoc integration, specifying the schema path and mode. ```javascript // next.config.js const withMarkdoc = require('@markdoc/next.js'); module.exports = withMarkdoc({ mode: 'static', // 'static' | 'server' schemaPath: './markdoc', // where tag/node/function schemas live tokenizerOptions: { allowComments: true } })({ pageExtensions: ['md', 'mdoc', 'js', 'jsx', 'ts', 'tsx'] }); ``` -------------------------------- ### Inline Tags Source: https://github.com/markdoc/docs/blob/main/pages/docs/tags.md Inline tags are automatically wrapped in a paragraph node. This example shows multiple inline highlight tags within a code tag. ```markdown {% code %} {% highlight %}Inline tag 1{% /highlight %} {% highlight %}Inline tag 2{% /highlight %} {% /code %} ``` -------------------------------- ### Configure Variables for Rendering Source: https://github.com/markdoc/docs/blob/main/pages/docs/config.md Define a configuration object to specify variables, such as `$version`, and pass it to the `transform` function. This allows dynamic content injection during rendering. ```javascript /** @type {import('@markdoc/markdoc').Config} */ const config = { variables: { version: "1.0" }}; const ast = Markdoc.parse("This is version {% $version %}"); const content = Markdoc.transform(ast, config); const html = Markdoc.renderers.html(content); ``` -------------------------------- ### Configure Next.js with Markdoc Source: https://github.com/markdoc/docs/blob/main/pages/docs/nextjs.md Update your `next.config.js` to enable Markdoc processing and specify page extensions. ```javascript const withMarkdoc = require('@markdoc/next.js'); module.exports = withMarkdoc(/* [options](#options) */)({ pageExtensions: ['md', 'mdoc', 'js', 'jsx', 'ts', 'tsx'] }); ``` -------------------------------- ### Transform AST to Renderable Tree with Config Source: https://context7.com/markdoc/docs/llms.txt Applies a configuration to an AST to produce a serializable renderable tree. Variables are resolved, and custom tags are processed. This is useful for server-side operations or passing data between client and server. ```javascript import Markdoc from '@markdoc/markdoc'; import yaml from 'js-yaml'; const source = ` --- title: My Page --- # {% $frontmatter.title %} {% if equals($env, "production") %} This only appears in production. {% /if %} {% callout type="warning" title="Heads up" %} Read this carefully. {% /callout %} `; const ast = Markdoc.parse(source); // Parse YAML frontmatter manually const frontmatter = ast.attributes.frontmatter ? yaml.load(ast.attributes.frontmatter) : {}; /** @type {import('@markdoc/markdoc').Config} */ const config = { variables: { frontmatter, env: 'production' }, tags: { callout: { render: 'Callout', attributes: { type: { type: String, matches: ['note', 'warning', 'caution', 'check'] }, title: { type: String } } } } }; const content = Markdoc.transform(ast, config); // Renderable tree shape (abbreviated): // { // name: 'article', // attributes: {}, // children: [ // { name: 'h1', attributes: {}, children: ['My Page'], $$mdtag: true }, // { name: 'Callout', attributes: { type: 'warning', title: 'Heads up' }, ... } // ], // $$mdtag: true // } ``` -------------------------------- ### Creating a Custom DateTime Attribute Type Source: https://github.com/markdoc/docs/blob/main/pages/docs/attributes.md Implement a custom attribute type by creating a class with `validate` and `transform` methods. This example creates a `DateTime` attribute. ```javascript export class DateTime { validate(value, config) { if (typeof value !== 'string' || isNaN(Date.parse(value))) return [ { id: 'invalid-datetime-type', level: 'critical', message: 'Must be a string with a valid date format' } ]; return []; } transform(value, config) { return Date.parse(value); } } ``` -------------------------------- ### Markdoc.transform(ast, config?) Source: https://context7.com/markdoc/docs/llms.txt Takes the AST produced by `parse` and applies the config (tags, nodes, variables, functions) to produce a serializable renderable tree. Variables are resolved to static scalar values at this stage. ```APIDOC ## Markdoc.transform(ast, config?) — Transform AST into a renderable tree Takes the AST produced by `parse` and applies the config (tags, nodes, variables, functions) to produce a serializable renderable tree. Variables are resolved to static scalar values at this stage. The renderable tree can be passed over the wire or used for server-side operations like building a table of contents. ```js import Markdoc from '@markdoc/markdoc'; import yaml from 'js-yaml'; const source = ` --- title: My Page --- # {% $frontmatter.title %} {% if equals($env, "production") %} This only appears in production. {% /if %} {% callout type="warning" title="Heads up" %} Read this carefully. {% /callout %} `; const ast = Markdoc.parse(source); // Parse YAML frontmatter manually const frontmatter = ast.attributes.frontmatter ? yaml.load(ast.attributes.frontmatter) : {}; /** @type {import('@markdoc/markdoc').Config} */ const config = { variables: { frontmatter, env: 'production' }, tags: { callout: { render: 'Callout', attributes: { type: { type: String, matches: ['note', 'warning', 'caution', 'check'] }, title: { type: String } } } } }; const content = Markdoc.transform(ast, config); // Renderable tree shape (abbreviated): // { // name: 'article', // attributes: {}, // children: [ // { name: 'h1', attributes: {}, children: ['My Page'], $$mdtag: true }, // { name: 'Callout', attributes: { type: 'warning', title: 'Heads up' }, ... } // ], // $$mdtag: true // } ``` ``` -------------------------------- ### Import Markdoc with CommonJS Source: https://github.com/markdoc/docs/blob/main/pages/docs/getting-started.md Import the Markdoc library using CommonJS syntax. ```javascript const Markdoc = require('@markdoc/markdoc'); ``` -------------------------------- ### Access Frontmatter in Markdoc Content Source: https://github.com/markdoc/docs/blob/main/pages/docs/nextjs.md Access the frontmatter object within your Markdoc content using the `$markdoc.frontmatter` variable. This example demonstrates displaying the frontmatter's title. ```markdown --- title: Using the Next.js plugin description: Integrate Markdoc into your Next.js app --- # {% $markdoc.frontmatter.title %} ``` -------------------------------- ### Extend Markdoc Configuration Source: https://github.com/markdoc/docs/blob/main/pages/docs/nextjs.md For advanced control over the Markdoc configuration, create a `/markdoc/config.js` file. This allows extending the config with additional data like records or utility functions, importing existing tags, nodes, and functions. ```javascript // markdoc/config.js import tags from './tags'; import nodes from './nodes'; import functions from './functions'; export default { tags, nodes, functions // add other stuff here }; ``` -------------------------------- ### Adding IDs to Headers with Annotations Source: https://github.com/markdoc/docs/blob/main/pages/docs/examples/index.md Demonstrates how to assign an ID to a Markdoc header using annotation syntax. This ID can then be used to link to the header, for example, in a table of contents. ```markdoc # My header {% #my-id %} ``` -------------------------------- ### Define Markdoc Tabs Tags Source: https://github.com/markdoc/docs/blob/main/pages/docs/examples/index.md Define the Markdoc tags for 'tabs' and 'tab' with their respective attributes and transformation logic. This setup is required before using the tags in your Markdoc documents. ```js import { Tag } from '@markdoc/markdoc'; const tabs = { render: 'Tabs', attributes: {}, transform(node, config) { const labels = node .transformChildren(config) .filter((child) => child && child.name === 'Tab') .map((tab) => (typeof tab === 'object' ? tab.attributes.label : null)); return new Tag(this.render, { labels }, node.transformChildren(config)); } }; const tab = { render: 'Tab', attributes: { label: { type: String } } }; /** @type {import('@markdoc/markdoc').Config} */ const config = { tags: { tabs, tab } }; ``` -------------------------------- ### Using Variables for Runtime Content Personalization Source: https://context7.com/markdoc/docs/llms.txt Demonstrates how to inject server-side data into Markdoc documents using variables. Variables are passed via `config.variables` and can be accessed using dot notation for nested objects, enabling personalized content rendering. ```javascript import Markdoc from '@markdoc/markdoc'; const doc = ` {% if $flags.showBeta %} ``` -------------------------------- ### Registering a Custom Attribute in Markdoc Config Source: https://github.com/markdoc/docs/blob/main/pages/docs/attributes.md Register your custom attribute type within the Markdoc `config` object. This example shows how to use the custom `DateTime` attribute for a tag. ```javascript import { DateTime } from './attribute-types/DateTime'; /** @type {import('@markdoc/markdoc').Config} */ const config = { tags: { 'tag-name': { render: 'YourComponent', attributes: { created: { type: DateTime, required: true } } } } }; ``` -------------------------------- ### Shorthand Attributes for ID and Class Source: https://github.com/markdoc/docs/blob/main/spec/index.md Shows shorthand attribute syntax for setting an ID and a class. ```markdoc {% #foo .bar %} ``` -------------------------------- ### Apply Shared Layout with Frontmatter Source: https://context7.com/markdoc/docs/llms.txt Use the '_app.js' file to apply a shared layout component and pass frontmatter data to it. ```javascript // pages/_app.js — apply a shared layout using frontmatter import Layout from '../components/Layout'; export default function App({ Component, pageProps }) { return (🇺🇸 United States 🇯🇵 Japan
``` -------------------------------- ### Client-Side Markdoc Rendering with React Source: https://github.com/markdoc/docs/blob/main/pages/docs/examples/react.md Fetches Markdoc content from the server and renders it using Markdoc's React renderer, mapping custom components like 'Callout'. ```javascript import React from 'react'; import Markdoc from '@markdoc/markdoc'; import { Callout } from './Callout'; export default function App() { const [content, setContent] = React.useState(null); React.useEffect(() => { (async () => { const response = await fetch( `/markdoc?` + new URLSearchParams({ path: window.location.pathname }), { headers: { Accept: 'application/json' } } ); if (response.status === 404) { setContent('404'); return; } const content = await response.json(); setContent(content); })(); }, []); if (content === '404') { returnPage not found.
; } if (!content) { returnLoading...
; } const components = { Callout }; return Markdoc.renderers.react(content, React, { components }); } ``` -------------------------------- ### Correct Variable Usage in Link Source: https://github.com/markdoc/docs/blob/main/pages/docs/variables.md Demonstrates the correct way to use a variable with a link by passing it to the `href` attribute of a custom `link` Tag. This is the recommended approach for dynamic link destinations. ```markdoc {% link href=$variable %}Link{% /link %} ``` -------------------------------- ### Including Partials in Markdoc Source: https://context7.com/markdoc/docs/llms.txt Shows how to include reusable Markdoc fragments (partials) in documents. Partials can be defined inline or loaded from disk. Variables can be passed scoped to a partial. ```javascript import Markdoc from '@markdoc/markdoc'; import fs from 'fs'; import path from 'path'; // Load partials from disk function loadPartials(dir) { return Object.fromEntries( fs.readdirSync(dir) .filter(f => f.endsWith('.md')) .map(f => [f, Markdoc.parse(fs.readFileSync(path.join(dir, f), 'utf8'))]) ); } /** @type {import('@markdoc/markdoc').Config} */ const config = { partials: { // Inline definition 'disclaimer.md': Markdoc.parse(`*All examples are for illustrative purposes only.*`), // Or load from disk: ...loadPartials('./markdoc/partials') } }; const doc = ` # SDK Reference {% partial file="disclaimer.md" /%} ## Authentication {% partial file="auth-header.md" variables={sdk: "Node.js", version: "3.0"} /%} `; const ast = Markdoc.parse(doc); const content = Markdoc.transform(ast, config); const html = Markdoc.renderers.html(content); ``` -------------------------------- ### Basic Markdoc Tag Usage Source: https://github.com/markdoc/docs/blob/main/spec/index.md Demonstrates a basic Markdoc tag with nested content. The opening and closing tags enclose a paragraph. ```markdoc {% example %} This paragraph is nested within a Markdoc tag. {% /example %} ``` -------------------------------- ### Using Custom Switch/Case Tags in Markdoc Source: https://github.com/markdoc/docs/blob/main/pages/docs/examples/index.md Illustrates the usage of custom 'switch' and 'case' tags in a Markdoc document to conditionally render content based on a primary value. ```markdoc {% switch $item %} {% case 1 %} Case 1 {% /case %} {% case 2 %} Case 2 {% /case %} {% /switch %} ``` -------------------------------- ### Import Markdoc with ESM Source: https://github.com/markdoc/docs/blob/main/pages/docs/getting-started.md Import the Markdoc library using ECMAScript Module (ESM) syntax. ```javascript import Markdoc from '@markdoc/markdoc'; ``` -------------------------------- ### Variable Syntax in Markdoc Source: https://github.com/markdoc/docs/blob/main/spec/index.md Demonstrates the syntax for defining and using variables in Markdoc. Variables can access nested data structures using dot notation and array indexing. ```markdoc {% foo=$bar.baz[10].qux %} ``` -------------------------------- ### Markdoc Annotations for Nodes Source: https://github.com/markdoc/docs/blob/main/pages/docs/syntax.md Demonstrates Markdoc annotations, used to pass attributes to nodes when HTML-like syntax is not applicable. Attributes are written in a separate `{%` and `%}` block following the node. ```markdoc {% table %} - Function {% width="25%" %} - Returns {% colspan=2 %} - Example {% align="right" %} {% /table %} ``` -------------------------------- ### Register Partials in Config Source: https://github.com/markdoc/docs/blob/main/pages/docs/partials.md Define partials by mapping file names to AST nodes in your Markdoc `config` object. This allows the default `partial` tag to locate and include the correct content. ```javascript /** @type {import('@markdoc/markdoc').Config} */ const config = { partials: { 'header.md': Markdoc.parse(`# My header`) } }; const doc = ` {% partial file="header.md" /%} `; const ast = Markdoc.parse(doc); const content = Markdoc.transform(ast, config); ``` -------------------------------- ### Include a Partial Source: https://github.com/markdoc/docs/blob/main/pages/docs/partials.md Use the `partial` tag to include content from another Markdoc file. ```markdoc {% partial file="header.md" /%} ``` -------------------------------- ### React Rendering with Markdoc Source: https://github.com/markdoc/docs/blob/main/pages/docs/render.md Render Markdoc content as React components. This involves transforming the document into a renderable tree and then using `Markdoc.renderers.react` with a mapping of tags to React components. ```javascript const tags = { callout: { render: 'Callout', attributes: {} } }; const doc = ` {% callout %} Attention, over here! {% /callout %} `; const ast = Markdoc.parse(doc); const content = Markdoc.transform(ast, { tags }); ``` ```jsx import Markdoc from '@markdoc/markdoc'; import React from 'react'; // or 'preact' function Callout({ children }) { return