​

Documentation project instructions

​

About this project

• Novu is the open-source notification infrastructure for in-app (Inbox), email, SMS, push, and chat
• This is a documentation site built on Mintlify
• Pages are MDX files with YAML frontmatter
• Configuration lives in docs.json
• Use the Mintlify MCP server, https://mcp.mintlify.com, to edit content and settings via MCP
• Use the Mintlify docs MCP server, https://www.mintlify.com/docs/mcp, to query information about using Mintlify via MCP

​

Terminology

• Use subscriber (not “user”) for notification recipients, identified by subscriberId
• Use workflow for the notification flow definition; step for individual nodes; trigger for invocation
• Use channel for delivery mediums: in-app/Inbox, email, SMS, push, and chat
• Use provider for the delivery service behind a channel (for example, SendGrid for email, Twilio for SMS)
• Use Inbox (capitalized) for the in-app notification component; avoid “notification center”
• Use topic for grouping subscribers for bulk notifications
• Use tenant for multi-tenant isolation when relevant using contexts feature
• Use integration for a configured provider connection in Novu
• Use environment for Development or Production contexts
• Use organization for the top-level account in the Novu Dashboard
• Use layout for email HTML wrappers; digest for aggregated notification batches
• Distinguish Novu Cloud from self-hosted deployments, and Community vs Enterprise editions where relevant

​

Style preferences

• Use active voice and second person (“you”)
• Keep sentences concise — one idea per sentence
• Use sentence case for headings
• Bold for UI elements: Click Settings
• Code formatting for file names, commands, paths, and code references
• Capitalize Novu and product names: Inbox, Framework, Dashboard
• Include frontmatter title and description on MDX pages
• Use sidebarTitle for short navigation labels when the page title is long (for example, SEO question-format titles)
• OpenAPI-backed API reference pages (openapi: "METHOD /path" in frontmatter) must not include a frontmatter description — Mintlify pulls the page description from the OpenAPI operation summary/description. Use title + openapi only, for example:

---
title: "Create an agent"
openapi: "POST /v1/agents"
---

• Optional 1–2 sentence intro prose before the OpenAPI block is fine on endpoint pages; do not duplicate that text as frontmatter description
• API schema reference pages use markdown tables (Field | Type | Description), not <ResponseField>. Escape union separators in the Type column as \| (for example, `string \| null`). Prefer Record<string, unknown> over { [k: string]: any; } in table cells.
• Provider integration pages use the title pattern {Provider} {Channel} Integration with Novu with sidebarTitle for the short provider name
• Use descriptive alt text on all diagrams and screenshots
• See SEO and GEO maintenance for the ongoing review checklist
• Use icons on top-level navigation section titles only (set "icon" on groups in docs.json), not on individual pages or nested collapsible groups
• For icons we use the Lucide library.
• Prefer Mintlify components (<Card>, <Columns>, <Steps>, <CodeGroup>) over raw HTML

​

API schema reference pages

• Use a markdown table with columns Field, Type, and Description.
• Do not use <ResponseField> — it is a legacy Mintlify component that is not supported in this docs setup and does not render reliably.
• Follow the pattern in docs/api-reference/agents/agent-schema.mdx and docs/api-reference/contexts/context-schema.mdx (intro prose + table when listing fields).
• OpenAPI-backed endpoint pages (openapi: "METHOD /path" in frontmatter) inherit request/response schemas from the spec; separate schema pages are only needed when you want a human-readable field glossary in the sidebar.

​

AI prompt blocks

<Prompt description="Add Novu Inbox to my Next.js app" icon="sparkles" actions={["copy", "cursor"]}>
# Add Novu Inbox to Next.js App

Install `@novu/nextjs`...
</Prompt>

• Integration setup where an AI assistant can implement code in the user’s repo (Inbox, workflow triggers, webhooks, agent connect buttons)
• MCP or skills pages where users paste operational prompts into connected AI tools
• Do not use for in-product Copilot-style chat or one-line examples better suited to prose

• Always set actions={["copy", "cursor"]} to match the Novu dashboard
• Use Lucide icons: sparkles (integration), bot (MCP/skills), zap (workflows), plug (agents)
• Use YOUR_* placeholders for dashboard-specific values (application identifier, subscriber ID, workflow ID)
• Add a <Note> near the first prompt on a page telling users to substitute values from API Keys, Subscribers, or Workflows in the dashboard
• Place prompts after prerequisites and adjacent to the code or setup steps they help implement

​

Server-side SDK code examples

1. Node.js
2. Python
3. Go
4. PHP
5. .NET
6. Java
7. cURL

• Derive SDK examples from the corresponding SDK reference page and the OpenAPI specification. The REST field name maps to workflowId in SDKs.
• Keep examples minimal and aligned across tabs — same workflow ID, subscriber ID, and payload shape.
• Use <YOUR_SECRET_KEY_HERE> or NOVU_SECRET_KEY placeholders; never hardcode real keys.
• Community SDKs (Kotlin, Laravel, Ruby) do not need tabs on platform pages unless the page is SDK-specific.
• Do not edit files under docs/.mintlify/skills/ in this repo — they are synced from novuhq/skills. Update trigger, subscriber, or preference skill examples there instead.

​

Content boundaries

• Document public platform features, SDKs, and API reference
• Do not document internal admin features, enterprise-only implementation details, or unreleased features
• Link to the glossary for term definitions rather than redefining them inline