Skip to main content

​
Purpose

This file serves as a guide for Codex agents (and any future automated systems or maintainers) on how to interpret, build, and maintain the documentation structure of this repository. The goal is to ensure consistent practices when updating content, adding new endpoint metadata, and verifying link integrity across the developer documentation site.

​
Documentation Structure Overview

This repository uses a Mintlify-based docs-as-code approach, designed for scalability and maintainability. Our content is primarily structured as:
  • v2/: Main directory for V2 documentation pages (MDX format)
  • community/: Community-facing documentation
  • docs.json: Defines navigation structure, themes, and site configuration
  • snippets/: Houses custom React components used across docs (e.g., contract address tables, interactive components)
  • data/: Includes machine-readable files like chainNamesSorted.json and dvnList.json which feed into live metadata rendering
  • images/: Static image assets
  • openapi/: OpenAPI specifications for API documentation

​
Local Development

To preview the documentation locally: 
npx mintlify dev
This starts a local development server (typically at http://localhost:3000). Changes to MDX files are reflected live without restarting.

​
Building and Deployment

Mintlify handles builds and deployment automatically when changes are pushed to the main branch. There is no local build step required. To validate your changes before pushing:
  1. Run npx mintlify dev to preview locally
  2. Check for broken links and component errors in the browser console
  3. Ensure all MDX files have valid frontmatter

​
Offline Metadata

Snapshot LayerZero metadata during setup: 
# In setup script
mkdir -p cache/metadata
curl -sSL https://metadata.layerzero-api.com/v1/metadata/deployments \
  -o cache/metadata/deployments.json
curl -sSL https://metadata.layerzero-api.com/v1/metadata/dvns \
  -o cache/metadata/dvns.json
curl -sSL https://metadata.layerzero-api.com/v1/metadata/defaultConfig \
  -o cache/metadata/defaultConfig.json
During code-mode, agents must read from local cache instead of live URLs:
  • cache/metadata/deployments.json: Contains all LayerZero onchain deployment addresses for every chain (Endpoints, Message Libraries, etc.)
  • cache/metadata/dvns.json: Contains DVN (Decentralized Verifier Network) records with contract addresses and endpoint IDs
  • cache/metadata/defaultConfig.json: Contains default crosschain configuration settings between Endpoints
Benefits:
  • Setup captures latest metadata during internet access
  • Code-mode runs fully offline using local JSON snapshots
  • Provides reference data for metadata-tools package and LayerZero configurations
This index provides chain information, endpoint IDs, and human-readable display names. It is used to:
  • Dynamically render chain tables and dropdowns
  • Populate real-time DVN/Executor deployments
  • Enable filters by mainnet/testnet/stage
If the structure of this endpoint changes, it may break live documentation components. When editing metadata files in data/, make sure the format remains compatible with the frontend logic in snippets/ consuming this data.

​
Codex Responsibilities

  • Run npx mintlify dev before finalizing any PR to preview changes and catch issues early.
  • Watch for changes to metadata files in data/ — additions to these files trigger workflows that dynamically update frontend displays.
  • Ensure consistency between metadata keys and usage across files (e.g., chainDisplayName, endpointId, stage, protocolVersion).
  • When adding new chains or endpoints, check that:
    • They are represented in both the metadata JSON and navigation (docs.json) if applicable.
    • Any related MDX files are correctly named and referenced.
  • Check if the glossary is missing any terms, and if so, update the v2/concepts/glossary.mdx page in alphabetical order to reflect.
  • If code snippets are outdated, compare with the local clone of workspace/devtools/packages/ and workspace/layerzero-v2/ to update references to protocol and contract standard code.

​
Summary

TaskCommand / Action
Preview docs locallynpx mintlify dev
Update chain metadataModify files in data/ as needed
Update navigationEdit docs.json navigation section
Confirm live index compatibilityEnsure structure matches /v1/metadata/deployments
Add/modify componentsEdit files in snippets/
For any questions or unexpected issues, ping the DevRel or Docs team. Codex should aim to maintain atomic, clean commits that ensure the developer experience remains seamless across updates.