Chainstack Developer Portal project context, structure, and formatting

Project context

This is a documentation project on the Mintlify platform
We use MDX files with YAML frontmatter
Navigation is configured in docs.json
When creating a new article as an *.mdx file, always remember to add the file name to the appropriate section in the navigation file docs.json
The docs use Mintlify's product switcher with two products:
- Platform — managed blockchain infrastructure (docs in docs/)
- Self-Hosted — deploy on your own infrastructure (docs in docs/self-hosted/)

Directory structure

dev-portal/
├── docs/                    # Platform documentation
│   ├── page-name.mdx
│   └── self-hosted/         # Self-Hosted documentation
│       ├── page-name.mdx
│       └── changelog/       # Self-Hosted release notes
├── images/                  # Platform images
│   └── self-hosted/         # Self-Hosted images
├── changelog/               # Platform release notes
├── openapi/                 # Platform API specifications
└── docs.json                # Navigation configuration for both products

Navigation structure (docs.json)

The navigation uses a product-based hierarchy:

products
└── product (Platform | Self-Hosted)
    ├── description
    ├── icon
    └── tabs
        ├── tab: "Guides"
        │   └── groups
        │       ├── group: "Group name"
        │       └── pages: ["docs/page", ...]
        └── tab: "Release notes"
            └── pages: ["changelog/entry", ...]

When adding a new page:

Create the .mdx file in the appropriate directory
Add the page path to the correct product → tab → group in docs.json

Example for Platform:

{
  "product": "Platform",
  "tabs": [{
    "tab": "Guides",
    "groups": [{
      "group": "Platform",
      "pages": ["docs/new-page"]
    }]
  }]
}

Example for Self-Hosted:

{
  "product": "Self-Hosted",
  "tabs": [{
    "tab": "Guides",
    "groups": [{
      "group": "Installation",
      "pages": ["docs/self-hosted/new-page"]
    }]
  }]
}

Internal linking

Use relative paths with the /docs/ prefix:

Platform pages: /docs/page-name
Self-Hosted pages: /docs/self-hosted/page-name

Examples:

See [System requirements](/docs/self-hosted/requirements) for details.
Learn more about [Global Nodes](/docs/global-elastic-node).

Cross-product linking is supported—you can link from Self-Hosted docs to Platform docs and vice versa.

Required page structure

Every page must start with frontmatter:

---
title: "Clear, specific title"
description: "Concise description for SEO and navigation"
---

Mintlify components

Callouts

<Note> for helpful supplementary information
<Warning> for important cautions and breaking changes
<Tip> for best practices and expert advice
<Info> for neutral contextual information
<Check> for success confirmations

Code examples

When appropriate, include complete, runnable examples
Use <CodeGroup> for multiple language examples
Specify language tags on all code blocks
Include realistic data, not placeholders
Use <RequestExample> and <ResponseExample> for API docs

Procedures

Use <Steps> component for sequential instructions
Include verification steps with <Check> components when relevant
Break complex procedures into smaller steps

Content organization

Use <Tabs> when deemed appropriate to show information in tabs-style next to each other in one row
Use <Accordion> for progressive disclosure
Use <Card> and <CardGroup> for highlighting content
Wrap images in <Frame> components with descriptive alt text

Release notes

The documentation has two products with separate release notes:

Platform — managed blockchain infrastructure (changelog.mdx + changelog/ directory)
Self-Hosted — deploy on your own infrastructure (docs/self-hosted/release-notes.mdx + docs/self-hosted/changelog/)

Platform release notes

Structure

dev-portal/
├── changelog.mdx
├── docs.json
└── changelog/
   ├── chainstack-updates-may-30-2025.mdx
   ├── chainstack-updates-april-1-2025.mdx
   └── [previous entries...]

Process

Update changelog.mdx: Copy the previous entry within <Update...> </Update> tags and paste it on top of the previous entry. Edit dates and content appropriately.

Example:

<Update label="Chainstack updates: May 30, 2025" description=" by Ake" >

**Protocols**. Now, you can deploy [Global Nodes](/docs/global-elastic-node) for Unichain Mainnet. See also [Unichain tooling](/docs/unichain-tooling) and a [tutorial](/docs/unichain-collecting-uniswapv4-eth-usdc-trades).

<Button href="/changelog/chainstack-updates-may-30-2025">Read more</Button>
</Update>

Create file in changelog/ directory: Use format chainstack-updates-may-30-2025.mdx. Paste the same entry content (without the <Update> tags) from step 1.
Update docs.json: In the Release notes section, add the newly created file name (without .mdx) between changelog and the previous release notes entries.

Example:

       "tab": "Release notes",
        "pages": [
          "changelog",
          "changelog/chainstack-updates-may-30-2025",
          "changelog/chainstack-updates-may-16-2025",

Self-Hosted release notes

Structure

dev-portal/
└── docs/self-hosted/
    ├── release-notes.mdx
    └── changelog/
        ├── chainstack-self-hosted-v1-0-0-january-28-2026.mdx
        └── [version entries...]

Process

Update release-notes.mdx: Add a new <Update> entry at the top.

Example:

<Update label="Chainstack Self-Hosted v1.0.0: January 28, 2026" description="">

**Initial beta release**. Deploy Ethereum Mainnet, Sepolia, and Hoodi full nodes on your own Kubernetes infrastructure using Reth execution client and Prysm consensus client.

<Button href="/docs/self-hosted/changelog/chainstack-self-hosted-v1-0-0-january-28-2026">Read more</Button>
</Update>

Create file in docs/self-hosted/changelog/ directory: Use format chainstack-self-hosted-v1-0-0-month-day-year.mdx.

The page title should match the label: "Chainstack Self-Hosted v1.0.0: January 28, 2026"

Update docs.json: In the Self-Hosted product's Release notes tab, add the new changelog page.

Node options master list

node-options-master-list.json is the main file for this Developer Portal where all the available node options are kept up to date. If you need a custom table with whatever options you want, you feed the master list to an LLM and generate your own table.

Relevant tables (updated on every master list change):

nodes-clouds-regions-and-locations.mdx
protocols-networks.mdx

When updating the master list:

Edit node-options-master-list.json
Regenerate dependent tables
Verify changes display correctly

API documentation requirements (Platform only)

These guidelines apply to Platform API documentation. Self-Hosted does not have API reference docs.

Document all parameters with <ParamField>
Show response structure with <ResponseField>
Include both success and error examples
Use <Expandable> for nested object properties
Always include authentication examples

OpenAPI 3.0 nullability (important for Try it)

When documenting JSON-RPC via OpenAPI 3.0, do not use type: null anywhere in schemas. OpenAPI 3.0 does not support a standalone null type and specs using it can cause Mintlify to fail matching the operation (e.g., removing the Try it button with an error about missing path/method).

Preferred pattern:

"result": {
  "type": "object",
  "nullable": true
}

Avoid patterns like:

"result": {
  "oneOf": [ { "type": "null" }, { "type": "object" } ]
}

If a page is missing the Try it button and logs show "no matching OpenAPI operation object" for a valid path/method, check and replace any type: null usages with nullable: true.

Quality standards

Test all code examples before publishing whenever possible
Use relative paths for internal links
Include alt text for all images
Ensure proper heading hierarchy (start with h2)
Check existing patterns for consistency

Content patterns

Single source of truth

Avoid duplicating information across pages. Instead, maintain one authoritative source and link to it:

System requirements → link to /docs/self-hosted/requirements
Supported protocols → link to /docs/self-hosted/supported-clients-and-protocols
Sync times and hardware recommendations → link to requirements page
Snapshot timeline → keep in FAQ, link from other pages

Example:

<!-- Instead of duplicating a table of requirements -->
See [System requirements](/docs/self-hosted/requirements) for specifications and a community-maintained list of hardware recommendations.

Troubleshooting page structure

For troubleshooting pages, use this hierarchy:

## Category (e.g., Installation troubleshooting)

### Problem heading (describes the symptom)

Brief description of the problem.

#### Cause or check 1

Diagnostic steps or solution.

#### Cause or check 2

Diagnostic steps or solution.

Avoid numbered lists for independent troubleshooting items—use subheadings instead.

Chainstack Developer Portal project writing style guide

Tone of voice

At Chainstack, we build complex tools for a primarily technical audience, displayed in a clear and intuitive way. Individuals and organizations use Chainstack as a stable foundation to support the infrastructure behind complex Web3 applications.

For these reasons, we always aim to:

Be clear, concise, and specific, not vague or convoluted.
Use correct terminology, while avoiding unnecessarily complex technical jargon.
Provide useful and true information.
Be friendly but not unprofessional.

Style tips

Use active voice. Avoid passive voice.

In active voice, the subject of the sentence does the action. In passive voice, the subject of the sentence has the action done to it.

Correct: Chainstack created a new network.
Incorrect: A new network was created by Chainstack.

Use positive language rather than negative language.

Correct: You need to delete all nodes to cancel your subscription.
Incorrect: You can't cancel your subscription because you have active nodes on your account.

Grammar

Spelling

We write using American English spelling.

Capitalization

We never use Title case. We use sentence case for everything, including titles.

Sentence case capitalizes the first letter of the first word, plus any proper nouns.

When writing out an email address or website URL, use all lowercase.

Example:

We keep the proper spelling and capitalization of project names.

Dates and time

Always use abbreviated months and days on forms, tables, lists and other condensed product elements. Non-abbreviated dates should be used in formal writing.

Date formats

Use abbreviated months for most contexts.

Correct:

Jul 28, 2019
July 2019

For formal writing, use full month names:

July 28, 2019

Date ranges

Date ranges must be written using an unspaced en-dash.

Correct:

Jul 28, 2019–Aug 29, 2019
Monday–Friday

Time formats

Use 24-hour format with colons, include timezone when relevant. Use en-dash for time ranges.

Correct:

09:00–23:59
09:00–23:59 (UTC+08:00)

Consistency rules

Never mix abbreviated and non-abbreviated formats in the same context.

Numbering format

We use the US-English number format. When labeling million we use "M" instead of "MM." When labeling thousands, we use "K".

Example:

4,294,967,295.00
1,000,000 = 1M

Pricing

Use commas (,) to separate thousands of pricing units. Cents are shown using periods (.) not commas (,).

The currency symbol always falls before the number. Three-letter currency codes can be denoted before the currency symbol if ambiguous.

Example:

$99
$9,999.99
USD $0

Punctuation

Hyphens and dashes

Use a hyphen (-) without spaces to link words into single phrase:

Example:

first-time user, top-up amount

Use en-dash to indicate a span or range for dates, times, and other ranges.

Examples:

Jul 23, 2023–Aug 1, 2023
Monday–Friday
09:00–17:00

Hyphens in prefixes "re" and "pre"

Don't use a hyphen (-) after prefixes "re" and "pre" unless its absence causes confusion.

Correct:

resend, rewrite, prehistoric
re-cover and re-creation as distinct from recover and recreation

Em dash

Em dashes can function as an alternative to parentheses, commas, or a colon.

In sentences and paragraphs

Use an em dash without spaces to indicate a break in flow or set off parenthetical information.

Examples:

It was a revival of the most potent image in modern democracy—the revolutionary idea.
My friends—that is, my former friends—ganged up on me.
Chainstack—a platform to manage decentralized networks and services—is actually the easiest to use.

In lists and technical documentation

Use an em dash with spaces when creating lists that explain or define terms, parameters, or concepts.

Examples:

Ethereum — a public distributed computing platform.
CHAINSTACK_NODE_ENDPOINT — your deployed Chainstack node.
code-level-variable — lowercase description of the variable.

Periods

Periods are used in most text elements that are not headings or interaction items.

Periods go inside quotation marks. They go outside parentheses when the parenthetical is part of a larger sentence, and inside parentheses when the parenthetical stands alone.

Commas

We make use of the Oxford comma. In a series of 3 or more items, use a comma before the final "and" or "or".

Correct: You need to delete all projects, networks, and nodes.
Incorrect: You need to delete all projects, networks and nodes.

Exclamation marks

Use exclamation marks sparingly, and never more than one at a time. They should be almost non-existent in product elements. Do not use them in failures or alert messages.

Colons

When a colon is used within a sentence, the first word following the colon is lowercased unless it is a proper noun.

When a colon introduces two or more sentences, speech in dialogue, a quotation or question, the first word following it is capitalized.

To merit a colon, the words that introduce a series or list must themselves constitute a grammatically complete sentence.

Correct:

The menagerie included cats, pigeons, newts, and deer ticks.

Incorrect:

The menagerie included: cats, pigeons, newts, and deer ticks.

Semicolons

Use a semicolon between two independent clauses not joined by a conjunction to signal a closer connection between them than a period would.

Dollar signs

Always escape dollar signs with a backslash in MDX files to prevent them from being interpreted as LaTeX/math delimiters.

Correct:

$1 USDC
$5M volume
$10,000

Incorrect:

$1 USDC
$5M volume
$10,000

Abbreviation

Use full naming in first mention of term in text. Abbreviate later instances.

Example:

You can deploy BNB Smart Chain (BSC) node endpoints on any Chainstack subscription plan.

Do not abbreviate Chainstack product names. Always use the full product name with proper capitalization.

Text elements

Navigation and menu items

Use sentence case.

Limit to one or two words.

No periods.

Example:

Documentation
Support
Settings
Sign out

Headings

Use sentence case.

Don't write in full sentences.

No periods.

Example:

Deploy your first blockchain node
Edit project
Network details

Descriptive text, paragraphs & subheadings

Use sentence case.

Use periods.

Example:

View your project members, and invite organizations to become project members.
Specify basic details. Note that these cannot be changed once the network is created.

Linking

Can be up to 5-10 words in length.

Use sentence case.

No periods if text link is on its own.

Use periods if link falls at the end of a regular sentence.

Don't link the punctuation at the end of a link.

Don't link the preceding article before the link.

Avoid one-word linking.

Use full links only for external resources.

Incorrect:

see our [Terms of Service].
visit the [documentation site]

Correct:

[Contact us]
[Review and rename nodes]
View the [Terms of Service] and [Privacy Policy].

Linking the words Chainstack and Chainstack account

Correct:

Use [Chainstack account](link) to link to console.chainstack.com
Use [Chainstack](link) for chainstack.com

Do not mix these two.

List items

Use sentence case and capitalize the first letter of each list item.

Keep all items in a list consistent—use either complete sentences or phrases throughout the entire list.

Punctuation rules for lists

Use periods when:

List items are complete sentences

Do not use periods when:

List items are single words, phrases, or sentence fragments

Bold text must never be the first element of a list item.

A list item may contain bold text later in the sentence (for example, to highlight a UI element), but the bullet or dash itself must start with plain text.

Exception: If the list item is a UI element name (per the UI‑elements rule), that name is allowed to appear in bold at the start of the line.

Correct:

Listed item — listed item explanation
Click Members — opens the project members page

Incorrect:

Listed item — listed item explanation

Examples

Complete sentences (use periods):

To downgrade your account, you need to:

Reduce your number of owned networks to 1.
Reduce your number of owned nodes to 1.

Single words or phrases (no periods):

Chainstack supports the following protocols:

Ethereum, Solana, BNB Smart Chain, Polygon, Arbitrum, Base, Optimism, Avalanche, TON, Ronin, Blast, ZKsync Era, Starknet, Scroll, Aptos, Fantom, Cronos, Gnosis Chain, Kaia, Moonbeam, Celo, Oasis Sapphire, Polygon zkEVM, Bitcoin, Harmony

Technical documentation lists with em dashes

For technical documentation lists that explain parameters, variables, or concepts, follow the em dash rules. Use em dashes with spaces and lowercase formatting:

List item — lowercase.
DOCS-LEVEL-VARIABLE — lowercase.
code-level-variable — lowercase.

Example:

Ethereum — a public distributed computing platform.
CHAINSTACK_NODE_ENDPOINT — your deployed Chainstack node.

If the list item is not a parameter explanation, but a parameter value, use ":" instead of an em dash:

Parameter name/explanation parameter: value

Example:

Decoded vout: 0

UI guidelines

UI elements

Use bold to denote UI elements.

Example: To see project members, click Members.

UI clickthrough

Use > to denote clicking through UI elements.

Example: To invite a member to the project, click Members > Invite member.

Note that only the UI elements are in bold, and the right angle bracket is not a UI element.

Full markdown code:

To invite a member to the project, click **Members** > **Invite member**.

UI as a word (Platform)

Never use UI as a word when providing instructions for the Chainstack console. Instead, use Chainstack.

Correct: On Chainstack, navigate to your node details
Incorrect: In the platform UI, navigate to your node details

UI terminology (Self-Hosted)

For Self-Hosted documentation:

Use Control Panel to refer to the Self-Hosted web interface
Use Chainstack Self-Hosted for the product name (not just "Chainstack")
Never use "Chainstack" alone when referring to Self-Hosted—this causes confusion with the managed Platform product

Examples:

Correct: Log in to the Control Panel
Correct: Chainstack Self-Hosted supports Ethereum Mainnet
Incorrect: Log in to Chainstack (ambiguous—could mean Platform)
Incorrect: On the Self-Hosted UI, navigate to... (use "Control Panel" instead)

Word usage

Word forms of cancel

Use American English (AmE) for word forms of cancel.

Canceling:

Correct: Canceling
Incorrect: Cancelling

Canceled:

Correct: Canceled
Incorrect: Cancelled

Cancellation:

Correct: Cancellation
Incorrect: Cancelation

Word forms of sync

Correct:

syncing, synced

Incorrect:

synching, synched

Currency vs. protocol in naming

Protocol names must always be capitalized.

Full currency names must always be lowercase, except when they appear at the beginning of a sentence or are part of code.

Examples:

wei, gwei, ether
The transaction fee is paid in ether. (lowercase)
Ether is the native cryptocurrency of Ethereum. (capitalized at start of sentence)

Ticker symbols must always be all caps and can be used in a sentence after explaining the acronym.

Examples:

Polygon token (MATIC)
Ether (ETH)
Wrapped ether (WETH)

Directory paths

End directory paths with a slash.

Correct:

F:\Documents\GitHub\
var/lib/

Incorrect:

F:\Documents\GitHub
var/lib

Directory vs. folder

Correct:

directory

Incorrect:

folder

Public repositories

Naming

The Chainstack open source public repositories must use lowercase-with-hyphens naming format.

Correct:

Description

The right-pane description must be in the following format:

Requirements:

One sentence max
No period at the end

FilesExpand file tree

CLAUDE.md

Latest commit

History

CLAUDE.md

File metadata and controls

Chainstack Developer Portal project context, structure, and formatting

Project context

Directory structure

Navigation structure (docs.json)

Internal linking

Required page structure

Mintlify components

Callouts

Code examples

Procedures

Content organization

Release notes

Platform release notes

Structure

Process

Self-Hosted release notes

Structure

Process

Node options master list

API documentation requirements (Platform only)

OpenAPI 3.0 nullability (important for Try it)

Quality standards

Content patterns

Single source of truth

Troubleshooting page structure

Chainstack Developer Portal project writing style guide

Tone of voice

Style tips

Grammar

Spelling

Capitalization

Dates and time

Date formats

Date ranges

Time formats

Consistency rules

Numbering format

Pricing

Punctuation

Hyphens and dashes

Hyphens in prefixes "re" and "pre"

Em dash

In sentences and paragraphs

In lists and technical documentation

Periods

Commas

Exclamation marks

Colons

Semicolons

Dollar signs

Abbreviation

Text elements

Navigation and menu items

Headings

Descriptive text, paragraphs & subheadings

Linking

Linking the words Chainstack and Chainstack account

List items

Punctuation rules for lists

Examples

Technical documentation lists with em dashes

UI guidelines

UI elements

UI clickthrough

UI as a word (Platform)

UI terminology (Self-Hosted)

Word usage

Word forms of cancel

Word forms of sync

Currency vs. protocol in naming

Directory paths

Directory vs. folder

Public repositories

Naming