Product overview page
The entry point for a product or plugin. Answers three questions: what is it, why use it, and how does it work.
Title and subtitle
Use “What is [Product]?” as the title. Add a one-line subtitle in the frontmatter
description field that summarizes the product in plain language.Opening paragraph
Two to three sentences. State what the product is, what it does, and where it fits in the Lerian ecosystem. Mention the licensing model (source-available, proprietary) and link to the GitHub repo if applicable.
Why use [Product]
Frame the problem the product solves. Use a bullet list for the key value propositions. Each bullet starts with a bold label followed by a colon and a one-line explanation.
What [Product] does
List core capabilities as bullets. Follow with a “Built for” subsection if the product serves distinct audiences (fintechs, banks, enterprises).
Common use cases
Use an
<AccordionGroup> with 3–5 use cases. Each accordion has a short title and a 2–3 sentence description of the scenario.How [Product] works
Use a
<Steps> component to walk through the high-level workflow (4–6 steps). Each step has a verb-based title and a 1–2 sentence explanation.Integrations (optional)
A table mapping related Lerian products to what they add.
| Product | Integration |
|---|---|
| Matcher | Reconcile ledger transactions against external data sources |
Architecture and concepts page
Explains the internal structure of a product — its domains, entities, and how they relate. This is the “About [Product]” page.
Opening paragraph
One paragraph that positions the product architecturally. Mention the domain-driven design if applicable.
Domains or components
Break the product into its logical domains (e.g., Onboarding Domain, Transaction Domain). Each domain gets an H3 heading with:
- A short description of its purpose
- A bullet list of its components, each with a bold name and a one-line definition
Getting started page
A hands-on tutorial that takes the reader from zero to a working setup. Target: under 15 minutes.
Title and subtitle
Use “Getting started with [Product]” as the title. The subtitle should set expectations: what the reader will accomplish and how long it takes.
Prerequisites
A table listing required tools with minimum versions and check commands.
Add a
| Tool | Minimum version | Check command |
|---|---|---|
| Go | 1.24+ | go version |
<Note> for OS compatibility.Numbered steps
Each step is an H2 with the format “Step N — [Verb] [object]” (e.g., “Step 1 — Clone the repository”). Inside each step:
- A 1–2 sentence explanation of what the step does and why
- A code block with the exact command
- A
<Tip>or<Note>for important details (ports, default values, gotchas)
Verification step
Always include a final step that confirms the setup works (e.g., check a balance, query a status endpoint).
Entity reference page
Documents a single core entity (Account, Ledger, Transaction, Holder, etc.). Explains what it is, how it behaves, and how to use it.
Opening definition
One paragraph defining the entity, its role in the system, and its relationship to other entities.
Core concepts
Explain key behaviors and rules. Use H3 subsections for distinct concepts. Include diagrams (
<Frame>) when relationships are complex.Code examples
Use
<CodeGroup> to show JSON and DSL examples side by side when both are supported. Use realistic payloads.Visual diagrams
Use
<Frame caption="Figure N. Description"> for architecture, flow, or entity relationship diagrams.Guide page
Explains how to accomplish a specific task or implement a use case. Task-oriented and contextual — explains the “why” alongside the “how.”
Opening context
One to two paragraphs explaining what the reader will accomplish, who this guide is for, and what problem it solves. Be specific — not “learn about X” but “configure X to handle Y.”
Step-by-step instructions
Use H2 sections for major phases. Within each phase, use numbered steps or
<Steps> components. Start each step with a verb.Include:- Code blocks with realistic payloads
<Tip>for best practices<Warning>for common pitfalls<Note>for important context
Plugin overview page
Plugin overviews follow the same structure as product overview pages, with these additions:
- State clearly whether the plugin is source-available or proprietary, and whether it requires a license.
- Specify the versioning relationship with Midaz (e.g., “CRM version always matches the Midaz Core version”).
- Include a deployment model section: how the plugin is deployed relative to Midaz (independently, same namespace, etc.).
- Add a requirements section listing what the institution needs to operate the plugin (ISPB, connectivity provider, DevOps maturity, etc.).
- If applicable, include a trade-offs and challenges section that honestly describes the operational responsibilities the plugin introduces.
Component patterns
These Mintlify components appear across all guide templates. Use them consistently.
| Component | When to use |
|---|---|
<Tip> | Best practices, recommendations, cross-references to API specs |
<Note> | Important context that isn’t a warning (OS compatibility, default values) |
<Warning> | Common pitfalls, things that will cause errors if ignored |
<Danger> | Security-critical information, data loss risks, compliance responsibilities |
<Steps> | Sequential workflows (getting started, how it works) |
<AccordionGroup> | Use cases, optional configurations, expandable details |
<CodeGroup> | Multiple code formats for the same operation (JSON + DSL, bash + YAML) |
<CardGroup> | Next steps, related pages |
<Frame> | Diagrams and illustrations with captions |
| Glossary tooltips | First occurrence of domain-specific terms in a page |