All Docs

Writing Markdown

Cognova uses MDC (Markdown Components) to render knowledge files, shared documents, chat messages, and documentation. MDC extends standard Markdown with syntax highlighting, component embedding, and more.

This guide covers what's supported and how to get the best results when writing knowledge files or shared documents.

Basic Formatting

Standard Markdown works everywhere:

# Heading 1
## Heading 2
### Heading 3

**Bold text** and *italic text* and ~~strikethrough~~

- Unordered list
- Another item
  - Nested item

1. Ordered list
2. Second item

> Blockquote for callouts or emphasis

[Link text](https://example.com)

![Image alt text](https://example.com/image.png)

Code Blocks

Fenced code blocks with a language identifier get automatic syntax highlighting powered by Shiki.

Inline Code

Use backticks for inline code: const x = 42 or pip install requests.

Fenced Blocks

Wrap code in triple backticks with a language identifier:

```python
def hello(name: str) -> str:
    return f"Hello, {name}!"
```

This renders with full syntax highlighting and a copy button.

Supported Languages

Cognova supports syntax highlighting for 60+ languages across all major ecosystems:

CategoryLanguages
Webjs, jsx, ts, tsx, vue, html, css, scss, json, json5, jsonc
Shellbash, sh, zsh, powershell, bat, fish
Systemsc, cpp, rust, go, zig
JVMjava, kotlin, scala, groovy
.NETcsharp, fsharp
Scriptingpython, ruby, perl, lua, php, r, elixir, erlang
Mobileswift, dart, objective-c
Functionalhaskell, ocaml, clojure, lisp
Markupmd, markdown, latex, xml, graphql
Configyaml, toml, ini, dotenv, nginx, dockerfile, hcl, prisma
Data & Querysql, csv, proto, regex
Systemsystemd, ssh-config, makefile, cmake
Otherdiff, log, mermaid, solidity

If no language is specified, the block renders as plain text without highlighting.

Examples

Python

import httpx

async def fetch_data(url: str) -> dict:
    async with httpx.AsyncClient() as client:
        response = await client.get(url)
        response.raise_for_status()
        return response.json()

Rust

fn fibonacci(n: u64) -> u64 {
    match n {
        0 => 0,
        1 => 1,
        _ => fibonacci(n - 1) + fibonacci(n - 2),
    }
}

SQL

SELECT agents.name, COUNT(conversations.id) AS total
FROM agents
LEFT JOIN conversations ON conversations.agent_id = agents.id
WHERE agents.workspace_id = :workspace_id
GROUP BY agents.name
ORDER BY total DESC;

Docker + YAML

FROM node:22-slim
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN corepack enable && pnpm install --frozen-lockfile
COPY . .
RUN pnpm build
CMD ["node", ".output/server/index.mjs"]

services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://localhost/cognova

Tables

Standard Markdown tables are supported with alignment:

| Left | Center | Right |
|:-----|:------:|------:|
| A    |   B    |     C |

Links & Images

External links open in a new tab automatically. Internal links use client-side navigation:

[External](https://github.com)
[Internal docs link](/docs/getting-started)
![Screenshot](/images/dashboard.png)

Horizontal Rules

Use three dashes for a horizontal rule:

---

Custom Components

Cognova extends Markdown with custom components using MDC syntax, powered by Nuxt UI prose components. Use ::component-name for block components and :component-name for inline components.

Callout

Highlight important information with colored callout boxes. Use the color prop for styling and icon for a leading icon.

::callout{color="info" icon="i-lucide-info"}
General information or context for the reader.
::

::callout{color="success" icon="i-lucide-lightbulb"}
A helpful tip or best practice.
::

::callout{color="warning" icon="i-lucide-alert-triangle"}
Something to watch out for — proceed with caution.
::

::callout{color="error" icon="i-lucide-alert-circle"}
A critical warning or breaking change.
::

Available colors: primary, secondary, success, info, warning, error, neutral

Code Group

Display multiple code blocks as tabs — useful for showing the same example in different languages. Each code block's filename or language becomes the tab label.

::code-group

```python [install.py]
pip install cognova
```

```javascript [install.js]
npm install @cognova/sdk
```

```bash [install.sh]
curl -fsSL https://cognova.dev/install | sh
```

::

The [filename] after the language sets the tab label. Without it, the language name is used.

Collapsible

Hide content behind an expandable section. Use name to label the section.

::collapsible{name="error output"}
Here is the complete stack trace that you can share with support...
::

Props: name (label text), openText (default "Show"), closeText (default "Hide")

Steps

Display ordered instructions with visual step indicators. Use ### headings inside to define each step.

::steps

### Create an API key

Go to **Settings → Integrations** and click "Create Key".

### Install the CLI

Run the install command for your platform.

\`\`\`bash
npm install -g @cognova/cli
\`\`\`

### Authenticate

\`\`\`bash
cognova auth login
\`\`\`

::

Badge

Inline status labels and tags. Renders with the primary color by default.

This feature is :badge[New] and supports :badge[Markdown]{color="info"} inside badges.

Card

Styled content card with optional title, icon, and description. Can also link somewhere with the to prop.

::card{title="Quick Start" icon="i-lucide-rocket"}
Clone the repo and run `pnpm dev` to get started in under a minute.
::

::card{title="API Reference" icon="i-lucide-code" to="/docs/rest-api"}
Browse all available REST API endpoints.
::

Icons use the Lucide icon set with the i-lucide- prefix.

Tips for Knowledge Files

When writing knowledge files that your agents will reference:

  • Use clear headings — agents search by heading relevance, so descriptive H2/H3 titles help retrieval
  • Keep sections focused — one topic per section makes it easier for agents to cite the right context
  • Include code examples — agents can reference and adapt code from your knowledge base
  • Use tables for structured data — parameter lists, API references, and comparison charts work well

Further Reading