Safrochain Documentation

The official documentation for Safrochain — an Africa-first Layer-1 blockchain built on the Cosmos SDK and CometBFT consensus. The site is published at https://docs.safrochain.com.

Looking for the chain itself? See Safrochain-Org/safrochain-node. This repository contains only the documentation site — markdown sources, design system, and the Docusaurus build config.

---

Table of contents

• What's in here
• Quick start
• Project layout
• Writing docs
• Available scripts
• Deployment
• Contributing
• Community & support
• License

---

What's in here

Section	Path	Audience
Introduction	docs/intro.md, docs/getting-started/	first-time visitors
Networks	docs/networks/	mainnet & testnet endpoints, chain registry
Run a node	docs/run-a-node/	node operators
Validators	docs/validators/	staking validators (incl. monitoring/Grafana, alerting, security, DR)
IBC & Relayers	docs/ibc/	relayer operators, IBC integrators
Developers	docs/cli/, docs/modules/	dApp developers
About	docs/protocol/, docs/resources/	tokenomics, governance, foundation, FAQ

The homepage and reusable React components live in src/. SEO defaults and route-level JSON-LD are in docusaurus.config.ts and src/clientModules/seo-jsonld.ts.

Quick start

git clone https://github.com/Safrochain-Org/docs.git safrochain-docs
cd safrochain-docs
npm install
npm start

Then open http://localhost:3000. Hot-reload is on by default — saving a markdown file refreshes the browser.

Prerequisites

Tool	Version	Notes
Node.js	≥ 20 (LTS)	use .nvmrc with nvm use
npm	≥ 10	bundled with modern Node
git	any recent	for branching and PRs

Yarn / pnpm work too; the lockfile committed here is package-lock.json.

Project layout

.
├── docs/                       # all markdown content (sidebar order from sidebars.ts)
│   ├── intro.md
│   ├── getting-started/
│   ├── networks/
│   ├── run-a-node/
│   ├── validators/             # full validator runbook (overview → DR)
│   ├── ibc/
│   ├── cli/
│   ├── modules/
│   ├── protocol/
│   └── resources/
├── src/
│   ├── clientModules/          # SEO + JSON-LD route hooks
│   ├── components/             # custom React components used in MDX
│   ├── css/                    # design system (custom.css)
│   └── pages/                  # homepage and standalone pages
├── static/                     # static assets (favicon, robots.txt, manifest, og images)
├── sidebars.ts                 # left-hand navigation tree
├── docusaurus.config.ts        # site config: SEO, themes, plugins
├── package.json
└── tsconfig.json

Writing docs

1. Create the file under the right section in docs/. File name becomes the URL slug (e.g. validators/monitoring.md → /validators/monitoring).

2. Add frontmatter:

   ---
   title: Page title that appears as <h1> and <title>
   description: Two-sentence summary used in search results and social cards.
   sidebar_position: 5
   keywords:
     - keyword 1
     - keyword 2
   ---

   If description contains a colon, wrap it in double quotes so YAML parses correctly.

3. Wire it into the sidebar in sidebars.ts. Pages without a sidebar entry are not discoverable from the navigation tree.

4. Build locally before pushing:

   npm run build

   The build runs in strict mode — broken links and broken anchors fail the build.

Style conventions

• Title case for title, sentence case for headings inside the page.
• Tabs are 2 spaces; markdown lists use -.
• Use ``` fenced code blocks with a language tag (bash, toml, yaml, json, go, rust, text for plain output).
• For copy-pasteable command blocks, prefer bash and avoid leading $.
• Em dashes (—) are intentionally avoided — use :, ,, or ; depending on context.
• Cross-reference internal pages with relative paths without .md, e.g. [Slashing & jail](./slashing).
• For architecture diagrams, prefer Mermaid (mermaid code block) over ASCII when the layout is non-trivial.

SEO checklist for every page

• title and description set in frontmatter
• keywords includes 4–10 relevant terms
• First paragraph is a self-contained answer to "what is this page?"
• At least one <h2> per major section
• All external links use https://
• No raw URLs in prose; use [text](url)

Available scripts

Command	Purpose
npm start	Run dev server with hot reload at http://localhost:3000
npm run build	Produce a production build into build/ (used by deploy)
npm run serve	Serve the built build/ directory locally
npm run clear	Clear Docusaurus cache (.docusaurus/)
npm run typecheck	Run tsc --noEmit over the TypeScript sources
npm run lint	Run ESLint over src/ and config

Deployment

The site auto-deploys on every push to main:

1. Push to main → CI workflow runs npm run build.
2. The build/ artifact is published to Vercel, which serves https://docs.safrochain.com from a global CDN.
3. Pull requests get a preview URL posted as a comment so reviewers can see the rendered site.

Manual deployment

If you ever need to deploy by hand:

npm install
npm run build
npx vercel deploy --prebuilt --prod

Production deploys require VERCEL_TOKEN, VERCEL_ORG_ID, and VERCEL_PROJECT_ID in your environment.

Contributing

We welcome documentation contributions of any size — typo fixes are as valuable as new sections. Read CONTRIBUTING.md before opening a PR.

By participating, you agree to abide by our Code of Conduct.

To report a security issue (in the docs or the chain), please follow SECURITY.md. Do not open public issues for security problems.

Community & support

Channel	Link	Use for
Discord	https://discord.gg/safrochain	real-time help, validator chat
Telegram	https://t.me/safrochain	community, announcements
X / Twitter	https://twitter.com/safrochain	network status, releases
GitHub	https://github.com/Safrochain-Org	code, issues, PRs
Email	hello@safrochain.com	partnerships, press

For a structured rundown of where to ask which question, see SUPPORT.md.

License

This documentation site is licensed under the Apache License, Version 2.0. The Safrochain name and logos are trademarks of the Safrochain Foundation; see docs/resources/brand-assets.md for usage guidelines.