v1.0.14 available changes!

Deployment Overview

The template comes with automated deployment to Fly.io using GitHub Actions. When you push changes or create a release, your documentation is automatically built and deployed.

Setting Up Fly.io

1. Create a Fly.io Account

Sign up at fly.io if you haven't already.

2. Install Fly CLI

# macOS/Linux
curl -L https://fly.io/install.sh | sh
# Windows
powershell -Command "iwr https://fly.io/install.ps1 -useb | iex"

3. Login to Fly

fly auth login

4. Create Your App

From the docs/ directory:

fly apps create your-app-name

5. Set Environment Variables

Add your environment variables to Fly:

fly secrets set GITHUB_REPO_URL=https://github.com/your-org/your-repo
fly secrets set GITHUB_BRANCH=main

6. Configure fly.toml

Edit fly.toml and update the app name:

app = "your-app-name"    Change this
[build]
  dockerfile = "Dockerfile"
[http_service]
  internal_port = 3000
  force_https = true
  auto_stop_machines = true
  auto_start_machines = true
  min_machines_running = 0
[[vm]]
  memory = '1gb'
  cpu_kind = 'shared'
  cpus = 1

GitHub Actions Setup

The template includes workflow files for automatic deployment. You need to place them in the root of your repository.

Workflow Location

your-repo/
 .github/
    workflows/
        deploy.yml           Main deployment
        deploy-release.yml   Release deployment
 docs/
    ...
 ...

Important: Workflows must be in the root .github folder, not inside docs/.github.

Required GitHub Secrets

Add these secrets to your GitHub repository (Settings → Secrets and variables → Actions):

• FLY_API_TOKEN - Your Fly.io API token (get it with fly tokens create deploy)

Deployment Triggers

The template supports two deployment workflows:

1. Continuous Deployment (deploy.yml)

   • Triggers on every push to main branch
   • Deploys latest documentation

2. Release Deployment (deploy-release.yml)

   • Triggers when you create a GitHub release
   • Generates versioned documentation

Versioning System

The template supports multiple documentation versions based on your git tags and releases.

How Versioning Works

1. Development Mode (local)

   • Uses .content-collections/ folder
   • No versioning, just live content

2. Production Mode (deployed)

   • Uses generated-docs/ folder
   • Organized by version

Generated Docs Structure

generated-docs/
 main/               Latest from main branch (no tags)
    content/
 v1.0.0/            Version 1.0.0 docs
    content/
 v2.0.0/            Version 2.0.0 docs
     content/

Generating Versioned Docs

Without Versions (Latest Only)

pnpm run generate:docs

This creates only the main/ folder with your latest documentation.

With Versions (All Releases)

pnpm run generate:docs -- --versions

This:

1. Fetches all git tags from your repository
2. Checks out each tag
3. Copies documentation for each version
4. Organizes everything in generated-docs/

Creating a Versioned Release

To create a new documentation version:

1. Update your documentation in the content/ folder
2. Commit and push your changes
3. Create a git tag:

git tag v1.0.0
git push origin v1.0.0

4. Create a GitHub release from that tag
5. Automatic deployment will generate versioned docs

Including Docs in Release Workflow

To automatically include documentation in your release workflow, modify your .github/workflows/release.yml:

name: Release
on:
  release:
    types: [published]
jobs:
  deploy-docs:
    runs-on: ubuntu-latest
    steps:
-      uses: actions/checkoutv3
-      name: Setup Node.js
        uses: actions/setup-nodev3
        with:
          node-version: '18'
-      name: Install dependencies
        run: pnpm install
-      name: Generate versioned docs
        run: pnpm run generate:docs -- --versions
        working-directory: ./docs
-      name: Deploy to Fly.io
        uses: superfly/flyctl-actions/setup-flyctlmaster
        with:
          version: latest
-      run: flyctl deploy --remote-only
        working-directory: ./docs
        env:
          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}

SEO Configuration

Robots.txt

By default, the template prevents indexing with x-robots-tag header. To enable indexing:

1. Remove the header from your CDN/Fly.io configuration
2. Or modify robots.txt in the public/ folder

Sitemaps

Sitemaps are automatically generated for all your documentation pages. They're available at /sitemap.xml.

llms.txt

An llms.txt file is automatically generated to help AI tools understand your documentation structure.

Monitoring Your Deployment

View Logs

fly logs

Check Status

fly status

SSH into Container

fly ssh console

Troubleshooting

Build Failures

• Check that all environment variables are set in Fly secrets
• Verify your fly.toml app name matches your Fly.io app
• Review logs with fly logs

Missing Versions

• Ensure git tags are pushed to your repository
• Run generate:docs -- --versions to regenerate
• Check that the generated-docs/ folder contains version folders

GitHub Actions Not Running

• Verify workflows are in root .github/workflows/, not docs/.github/workflows/
• Check that FLY_API_TOKEN secret is set in GitHub
• Review GitHub Actions logs for errors

Manual Deployment

If you need to deploy manually:

# From the docs/ directory
fly deploy

This builds and deploys your documentation directly to Fly.io without going through GitHub Actions.