Special Symbols

xyd provides several special symbols that enhance your markdown content. Learn how to use them below.

Component Directive

Component Directive (:::<component>) is used to render UI components directly in your markdown:

:::callout
This is a callout component
:::

to pass props into component use {<key>=<value>}:

:::callout{kind="warning"}
Take care!
:::

:::callout{kind="warning" icon="⚠️"}
You can pass multiple too!
:::

if component props accept booleans you can use sugar syntax:

:::my-component{mybool}
Bool true sugar syntax
:::

// for negation
:::my-component{!mybool}
Bool false sugar syntax
:::

if component does not have a children prop you can use shorter directive syntax(::):

::my-component{label="Cool"}

if nested components, parent must use extra ::

::::my-parent-component
  :::my-component
  You can pass nested too!
  :::
:::

Function Calling

Function Calling (@<function>) is used to execute functions within your markdown content:

@import "~/snippets/Hello.ts"

Output VariableComing Soon

Output Variable (@out(<name>=<expression>)) is used to pass output variables from content files, useful for composing documentation content:

@out(examples=(
  ```md
  :::callout
  Note that you must have an Admin or Owner role to manage webhook settings.
  :::
  ```
))

or if output variable is a callback:

@.examples(title="Samples")
```md
:::callout
Note that you must have an Admin or Owner role to manage webhook settings.
:::
```
@end

Output Variable API

Define your own custom output variable using follow API:

export default {
  outputVariables: {
    examples: Examples
  }
}

function Examples({title, children}) {
  // your custom logic here
}

Read VariableComing Soon

Read Variable ({<read_variable>}) is used to access read variables from page meta and other pages:

{page.title}

Attributes

Some built-in tags has abilities to pass attributes (<tag|expression>[<attributes>]):

## Hide me from TOC [!toc]

## Add me to TOC while not render on page [toc]

## Component Directive (`:::`) [toc="Component Directive"]

Full Example

Here's how you can combine all these symbols in a single markdown file:

---
title: Special symbols usage
---

@.toc(anchor="bottom")
:::toc-card{title="Starter" href="https://github.com/xyd-js/starter"}
  Check out our starter repo
:::
@end

# {page.title}

## Import Example {toc="Import example"}
You can import code snippets using the `@import` function:

@import "~/snippets/my-snippet.ts"

:::callout
`~` refers to the local path of your docs.
:::

Summary

These special symbols provide powerful ways to enhance your markdown documentation:

• Components: Add rich UI elements directly in markdown
• Functions: Import and execute code dynamically
• Variables: Pass data between content files
• Page Meta Access: Use metadata from your content files

By combining these features, you can create interactive and dynamic documentation with minimal effort.