​

Median documentation: agent instructions

For general Mintlify product knowledge (components, configuration), install the Mintlify skill: npx skills add https://mintlify.com/docs

​

About this project

• This is the documentation for Median, published at docs.median.co and built on Mintlify.
• Pages are MDX files with YAML frontmatter in docs/. Each page’s URL is its path, for example docs/status-bar.mdx is served at /docs/status-bar.
• Navigation, navbar, footer, colors, fonts, and redirects live in docs.json.
• Reusable components live in snippets/. Images live in images/.
• The docs were migrated from ReadMe. Page paths were kept the same so existing links keep working. Don’t rename a page without adding a redirect.
• This repository is public. Anything committed here, including hidden pages and Git history, is readable on GitHub.
• 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 look up how Mintlify works.
• The writing and visual rules below follow the Median Brand Guidelines (version 1.0, December 2023). When this file and the brand guidelines disagree, ask the user instead of guessing.

​

Files you must not edit by hand

• docs/changelog.mdx and docs/changelog-archive.mdx are generated daily from a Google Sheet by a GitHub Action in a separate private repository. Manual edits are overwritten on the next sync. Change the sync script’s template instead.
• changelog-tags.js and changelog-tags.css style the changelog tags. Keep the tag list in changelog-tags.js in sync with the release types and products in the sync script.

​

Voice

1. We’re the experts. State facts clearly and confidently, then back them up with evidence: working code, exact settings, and links to official platform docs. Don’t hedge (“should probably work”) and don’t make claims you can’t show.
2. We get to the point. Lead with what the reader can do and what they need. Keep word count low. Use short paragraphs, bullets, tables, and bold UI labels so readers can scan.
3. We’re refreshingly honest. Say up front when something costs money, needs a specific plan or plugin, works on only one platform, or has a known limitation. Put it in the introduction or a callout, not at the bottom. If Median isn’t the right tool for a use case, say so.
4. We’re human. Be friendly, calm, and professional. Use contractions (“you’ll”, “don’t”) and address the reader as “you”. An occasional rhetorical question or exclamation point is fine. Never use one in a warning or error message.
5. We don’t just speak in </code>. Explain the concept in plain language before the technical detail, and define jargon on first use. Then go as deep as advanced readers need.

​

Terminology

• “Dashboard” is fine for third-party products, such as the OneSignal dashboard. Median’s own interface is always App Studio.
• Service names keep the capitalization the brand uses: Self-Service, Assisted App Development, Concierge App Development, Full-Service, and Enterprise. Only mention a service if an existing page or the user confirms it’s current.
• median.* methods come from the library injected into the app. Median.* methods come from the median-js-bridge npm package. Don’t mix them in one example.
• Keep official third-party names as written: Firebase Cloud Messaging, OneSignal, App Store Connect, Google Play Console, Microsoft Entra ID, Microsoft Dynamics 365.

​

Style

• US English: “behavior”, “color”, “practices”.
• Active voice and second person (“you”).
• Short sentences, one idea per sentence. Prefer a colon or a new sentence to an em dash, and use at most one em dash per sentence.
• Oxford comma, always: “iOS, Android, and the web”.
• Sentence case for page titles, sidebar titles, headings, and card titles. Capitalize only proper nouns: Median product names (App Studio, JavaScript Bridge, Publishing Service), third-party brands (OneSignal, Google Sign-In), and platform names. Generic features are lowercase: “Share button”, “Getting started with Replit”, “Pull-to-refresh”.
• Use imperative headings for tasks: “Create an instance”, “Send to a topic”.
• Bold for UI elements, with arrows for paths: Native Plugins → OneSignal. Write UI labels exactly as App Studio shows them, even when they’re title case.
• Code formatting for file names, paths, method names, parameters, and values.
• No marketing language in docs: avoid “powerful”, “seamlessly”, “leading”, “unbelievably”, and “at precisely the right moment”. The brand principle is “show, not tell”, so show the result instead.
• No emoji in docs pages, headings, or callouts. The brand reserves emoji for social media.
• Use descriptive link text. Never “here” or “click here”.
• Don’t repeat the same explanation in several sections. Explain once and link to it.

​

Frontmatter

---
title: "Status bar"
description: "Control the color and style of the device status bar in your app."
---

• The title is in sentence case (see Style). It’s also the sidebar label, unless you set a shorter sidebarTitle.
• The description is a full sentence ending with a period, about 150 to 160 characters at most. It’s used as the subtitle and as the meta description for search engines, so say what the reader can do on the page.
• Don’t repeat the title as an H1 in the page body. Mintlify renders the title as the H1, so the page starts at H2.
• Hidden pages (not in docs.json navigation) get noindex: true.
• Deprecated pages get deprecated: true and a <Warning> at the top that links to the replacement page.

​

Page structure

1. Introduction: what the feature does and when to use it, in one or two short paragraphs. State costs, plan or plugin requirements, and platform limits here.
2. Developer Demo callout (see below), if a demo page exists.
3. Prerequisites.
4. Configuration: App Studio settings as a table with Setting, Description, and, where helpful, Recommendation columns.
5. JavaScript Bridge methods: one H3 per method or feature.
6. Testing checklist, for complex integrations.
7. Troubleshooting: one H3 per problem, phrased as the symptom (“Push notifications aren’t arriving”), so support replies can link to it.
8. Related documentation: a CardGroup.

​

Components and patterns

• Start a callout with a bold line, not a heading. Headings inside callouts appear in the table of contents.
• Developer Demo callouts use this exact format:

<Check>
  **Developer Demo**

Display our demo page in your app to test during development [https://median.dev/status-bar/ <Icon icon="arrow-up-right-from-square" size={12} />](https://median.dev/status-bar/)

</Check>

​

JavaScript Bridge code

import { MedianLogo } from "/snippets/median-logo.jsx";

<MedianLogo />

<CodeGroup>

```javascript JavaScript
median.statusbar.set({ style: "dark", color: "80ff0000" });
```

</CodeGroup>

• Use lowercase language tags (javascript, json, bash) with a title after them. Use text for AI prompts and plain output.
• Put related variants (for example Set / Get, or Subscribe / Unsubscribe) as tabs in one CodeGroup.
• Examples must be valid code readers can copy. Don’t use pseudo-syntax like stop(true | false). Show real values and explain the options in a table.
• Guard calls that only work in the app: if (typeof median !== 'undefined') for the injected library, or Median.isNativeApp() for the npm package. Prefer median_library_ready() for code that runs on page load.
• Use console.log in example handlers, not window.alert().

​

Cards

• Use CardGroup and Card. Icons are Font Awesome names without the fa- prefix (icon="puzzle-piece"), or an image path for partner logos. See Icons for which icons fit the brand.
• Columns: cols={1} for workflow lists, cols={2} for related documentation, cols={3} for landing pages with short descriptions.
• A card links once, through href. Don’t add “Learn more” links inside cards.
• Card titles are in sentence case. Card descriptions are one sentence and don’t repeat the title.

​

Other components

• <Steps> for procedures where readers follow an order.
• <Tabs> for platform- or client-specific instructions (iOS / Android, Claude / Cursor / VS Code).
• <AccordionGroup> for long reference content and FAQs.
• <Frame> around every image, with a caption where helpful.
• <Prompt description="..."> for AI prompts readers should copy. The description says what the prompt does. Don’t repeat the prompt text elsewhere.
• <AppetizeEmbed iosEmbedCode="..." androidEmbedCode="..." /> from /snippets/appetize-embed.jsx for live simulators. Pass only the platforms you have.
• <InstantPreviewCTAInline articleType="lovable" /> from /snippets/instant-preview-cta-inline.jsx on website builder pages. Always set articleType (replit, lovable, base44, salesforce, bolt).

​

Diagrams

• Use Mermaid in a ```mermaid code block.
• Prefer flowchart LR to keep diagrams short. Use short node labels in sentence case.
• Keep code and JSON out of diagram nodes. Show them in a code block below the diagram.
• Don’t hide a diagram that explains core behavior inside an accordion.
• To use brand colors, start the diagram with this line, and check the result in both light and dark mode in the preview:

%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#B5DAFF", "primaryTextColor": "#1A100B", "primaryBorderColor": "#1174D3", "secondaryColor": "#FEB9FF", "tertiaryColor": "#FFEFB4", "lineColor": "#7D7A77", "fontFamily": "DM Sans"}}}%%

​

Tables

• Use Markdown tables, not HTML. Use an HTML table only when cells need vertical alignment.
• Split very wide tables. Prefer languages or items as rows and a few columns over many columns.

​

Brand and visual identity

​

Logo

• Use only the official logo files from the Median Brand Kit. Never recreate, recolor, rotate, stretch, outline, or add shadows, gradients, or other effects to the logo.
• Use the classic logo (dark text) on light backgrounds and the dark-background version (light text) on dark backgrounds. In docs.json, these are the light and dark logo and favicon entries.
• On a colored background or a photo, use the monochrome logo, or place the logo in a contained light or black box. Never put the full-color logo directly on a photo.
• The logo is never shorter than 24px on screen. Keep clear space around it at least as wide as one unit of the logomark grid.
• Use the logomark on its own only where space is square and small, such as the favicon or an app icon.
• For partner lockups, use the format Median × Partner, match the visual weight of both logos, and use each partner’s official logo unchanged.

​

Colors

• Colored text on a white background uses Darker Blue (#1174D3). It’s the only Base or Darker color that meets the WCAG AA contrast minimum for normal text on white (4.7:1). Don’t use pink or yellow for text on light backgrounds.
• Colored text on a dark background uses the Base colors.
• For tinted backgrounds, such as badges or highlighted boxes, use the Lighter colors with Median Black text in light mode, and the Base colors with Median Black text in dark mode.
• Dark surfaces use Darker Black (#0E0D08) with Median White text.
• Keep at least one brand color in otherwise black-and-white compositions.

​

Typography

• docs.json sets Questrial for headings and DM Sans for body text. Don’t set fonts in MDX, snippets, or inline styles.
• Code uses Mintlify’s monospace font.

​

Icons

• The brand’s icon system is IBM Carbon, which Mintlify can’t load as a library. Use Font Awesome in the default regular (outline) style, which is closest to Carbon. Don’t use the solid, duotone, or sharp styles for interface icons.
• Partner logos in cards are images, not icons.

​

Images and screenshots

• Store images under images/docs/docs/<feature>/, for example images/docs/docs/system-nav-bar/3button.png, and reference them as /images/docs/docs/<feature>/<file>.
• Never reference files.readme.io or other ReadMe-hosted images. Download them into the repo.
• Every image needs descriptive alt text.
• Check that logos and screenshots are readable in both light and dark mode.

​

Links

• Internal links are relative and include /docs/: [Status bar](/docs/status-bar). Never use https://docs.median.co/... or https://median.co/docs/....
• Never link to median.readme.io, gonative.readme.io, or docs.median.co/discuss.
• External links are regular Markdown links. Link to official docs (Apple, Google, Firebase) instead of copying details that change often, such as fees, regional rules, or device lists.

​

docs.json navigation

• Top-level groups in a tab are section headings. Never add root to a top-level group. It makes the section collapse.
• Nested groups set root to their overview page, so clicking the group name opens it. Don’t also list the root page in pages, or it appears twice.
• Each page appears in the navigation once.
• Group names are in sentence case, except for product and brand names.
• Hidden pages are left out of navigation (or placed in a group with "hidden": true). They’re still built and reachable by URL.
• When renaming, merging, or removing a page, add a redirect to the redirects array.
• Use relative paths for internal links in docs.json (navbar, logo, redirects).

​

MDX pitfalls that break the build

• Indented closing tags after a list. A closing tag like </Warning> or </Info> indented directly under a list item is parsed as part of the list. Closing tags of callouts always start at column 1.
• Curly braces in text. { and } outside code are parsed as JavaScript. Escape them (\{ style: "x" \}) or put the text in backticks. This applies inside <Prompt> too.
• Code fences on one line. Opening and closing ``` must each be on their own line.
• Blank lines inside JSX (for example inside <video> or between <source> tags) can turn content into Markdown paragraphs.
• Unpaired backticks and spaces inside code spans (`foo `bar) render incorrectly.
• Duplicate headings on a page create duplicate anchors. Make each heading unique.

​

Validation

npx mint validate      # MDX parse errors and content checks
npx mint broken-links  # internal links

​

Content boundaries

• Don’t commit secrets, API keys, customer names or data, discount codes, or review incentives. The repository and its history are public, even for hidden pages.
• Don’t invent App Studio menu paths, setting names, default values, or plugin behavior. If something isn’t confirmed by an existing page or the user, add it as an open question for the user instead of guessing.
• Don’t invent prices, plan names, guarantees, or service terms. Link to the pricing page instead of copying prices.
• Don’t document internal tools or the private release notes sync repository.
• Don’t change the logo, brand colors, or fonts. Those come from the Median Brand Kit.
• When a change affects behavior described on other pages (for example a parameter like persist), find and update those pages in the same change.