Second documentation

This is the technical documentation for the Ark protocol and tooling by Second. The documentation is built using Material for MkDocs.

Contributing

We welcome contributions and updates to the documentation! To contribute:

1. Make your changes to the documentation files
2. Test your changes locally using the setup instructions below
3. Submit a pull request describing your changes

Project structure

docs/ # Git repository root
├── mkdocs.yml # Main configuration
├── mkdocs.insiders.yml # Insiders configuration (optional)
├── rebuild_social_cards.sh # Script to regenerate social cards
├── layouts/ # Custom social card layouts (for Insiders)
│ └── custom.yml
├── docs/ # Documentation content (edit these files)
├── overrides/ # Template customizations
├── requirements.txt # Python dependencies
└── pyproject.toml # Project configuration

Setting up locally

Prerequisites

Install uv:

uv is a fast Python package installer that handles dependencies and environments automatically.

# Linux and macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

Install system dependencies:

You'll need Cairo and imaging libraries for social card generation.

Linux (Ubuntu/Debian):

sudo apt update
sudo apt install libcairo2-dev libfreetype6-dev libffi-dev libjpeg-dev libpng-dev libz-dev

Linux (CentOS/RHEL/Fedora):

sudo dnf install cairo-devel freetype-devel libffi-devel libjpeg-devel libpng-devel zlib-devel

macOS:

brew install cairo freetype libffi libjpeg libpng zlib

Running the documentation server

For all contributors (no Insiders access needed):

# Clone the repository
git clone git@codeberg.org:ark-bitcoin/docs.git
cd docs
# Start the development server (uv handles everything automatically)
uv run mkdocs serve

The documentation will be available at http://127.0.0.1:8000. The server will automatically reload when you make changes to files in docs/ (the markdown content directory).

Note: This uses the standard Material for MkDocs configuration (mkdocs.yml) which works perfectly for editing documentation content. You'll have full access to all documentation features—Insiders is only needed for custom social card generation.

Building static files

To generate the static HTML files (for testing how the final site will look):

# From the repository root
uv run mkdocs build

This creates a site/ directory with the generated website.

Troubleshooting

"Cairo not found" or imaging errors:

• Make sure you installed the system dependencies listed in Prerequisites

Development server won't start:

• Ensure you're in the repository root (where mkdocs.yml is located)
• Check that uv is installed: uv --version

Changes not showing up:

• The server auto-reloads, but you can restart it if needed
• Ensure you're editing files in docs/ (the markdown content directory)

Material for MkDocs Insiders (Optional)

This section is only for project maintainers with GitHub sponsorship. Regular contributors should use the standard setup above and can skip this section entirely.

Understanding the two workflows

Second sponsors Material for MkDocs to access Insiders features like custom social card generation.

Regular contributors:

• Use uv run mkdocs serve (no additional setup)
• Automatically get the public Material for MkDocs version
• Full access to all documentation content and editing features
• Social cards use default layouts

Maintainers with Insiders access:

• Use uv run mkdocs serve -f mkdocs.insiders.yml (after setup below)
• Get the Insiders Material for MkDocs version
• Can test custom social card layouts defined in layouts/custom.yml
• All documentation content works exactly the same

Setup for maintainers with Insiders access

Prerequisites:

1. Be a sponsor of squidfunk/mkdocs-material
2. Request addition to the Insiders repo as a contributor
3. Create a GitHub Personal Access Token with repo scope

Installation:

# Set your GitHub token (required for private Insiders repo access)
export GH_TOKEN='ghp_your_token_here'
# From the docs directory, install Insiders into your virtual environment
cd docs
uv pip install "git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git"
# Verify Insiders is installed
uv run --no-sync python -c "import material; print(material.__version__)"
# Should show: 9.6.x+insiders-x.x.x
# Run with Insiders features enabled (use --no-sync to prevent reverting to public version)
uv run --no-sync mkdocs serve -f mkdocs.insiders.yml

Why --no-sync? By default, uv run syncs the environment to match pyproject.toml (which specifies the public version). The --no-sync flag prevents this, keeping your manually-installed Insiders version.

Critical: Why we use uv pip install instead of uv add

• ✅ uv pip install - Installs only in your local .venv (gitignored), safe to commit your work
• ❌ uv add - Modifies pyproject.toml and uv.lock, breaks setup for regular contributors

Using uv pip install ensures maintainers with Insiders access can work on the documentation without breaking the project for contributors who don't have Insiders.

Regenerating social cards

The project includes a convenient script to rebuild all social card images (Open Graph images for social media sharing).

Prerequisites: You must have Insiders installed (see setup above). The script will check and warn you if Insiders is missing.

Quick rebuild:

# From repository root
./rebuild_social_cards.sh

This script will:

• Check that Insiders is installed (exits if missing, unless you force continue)
• Stop any existing servers
• Clean and rebuild with Insiders configuration
• Regenerate all social card images with custom branding
• Show where cards are located: site/assets/images/social/

Without Insiders: Social cards will be generated with default layouts (no custom logo, colors, or typography).

To view the generated site:

# From repository root
cd site && python3 -m http.server 8001
# Then open http://127.0.0.1:8001 in your browser

To view social card images directly:

# From repository root
open site/assets/images/social/

Note: Social cards are automatically generated based on:

• Page titles (from H1 headings)
• Page descriptions (from frontmatter description field)
• Custom layout defined in layouts/custom.yml