Launch Your Documentation

Deploy your Mordoc documentation to any hosting platform that serves static sites. This guide covers popular options and deployment strategies.

Deployment Overview

Mordoc generates static HTML files that can be hosted anywhere:

• Static hosting platforms: Netlify, Vercel, Cloudflare Pages
• Cloud storage: AWS S3, Google Cloud Storage, Azure Blob Storage
• Traditional hosting: Shared hosting, VPS, dedicated servers
• CDN platforms: Cloudflare, Fastly, AWS CloudFront

Pre-Deployment Checklist

Before deploying:

• [ ] Build completed successfully: npm run build
• [ ] Tested locally: npm run preview
• [ ] All links verified
• [ ] Search functionality tested
• [ ] Configuration finalized
• [ ] baseUrl set correctly in config/site.json
• [ ] Changes committed to version control

Popular Hosting Platforms

Netlify

Pros: Easy deployment, free tier, automatic HTTPS, preview deployments

Deploy with Git Integration

1. Push your code to GitHub
2. Go to netlify.com
3. Click "Add new site" → "Import an existing project"
4. Connect to GitHub
5. Select your repository
6. Configure build settings:
   • Build command: npm run build
   • Publish directory: dist
7. Click "Deploy site"

Deploy via Drag & Drop

1. Build locally: npm run build
2. Go to netlify.com
3. Drag dist/ folder to deploy area
4. Site is live immediately

netlify.toml Configuration

Create netlify.toml in project root:

[build]
  command = "npm run build"
  publish = "dist"

[[redirects]]
  from = "/*"
  to = "/404.html"
  status = 404

Vercel

Pros: Excellent performance, free tier, serverless functions, automatic deployments

Deploy with Git

1. Push to GitHub/GitLab/Bitbucket
2. Go to vercel.com
3. Click "Add New" → "Project"
4. Import your repository
5. Configure:
   • Framework Preset: Other
   • Build Command: npm run build
   • Output Directory: dist
6. Click "Deploy"

vercel.json Configuration

{
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "rewrites": [
    { "source": "/(.*)", "destination": "/" }
  ]
}

Cloudflare Pages

Pros: Global CDN, free tier, fast, DDoS protection

Deploy with Git

1. Push to GitHub/GitLab
2. Go to pages.cloudflare.com
3. Click "Create a project"
4. Connect your Git account
5. Select repository
6. Configure:
   • Build command: npm run build
   • Build output directory: dist
7. Click "Save and Deploy"

GitHub Pages

Pros: Free for public repos, simple setup, integrated with GitHub

GitHub Actions Deployment

Create .github/workflows/deploy.yml:

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - run: npm ci
      - run: npm run build
      
      - uses: actions/upload-pages-artifact@v2
        with:
          path: dist
  
  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/deploy-pages@v2
        id: deployment

Enable GitHub Pages in repository settings:

1. Settings → Pages
2. Source: GitHub Actions
3. Save

Note: Update baseUrl in config/site.json:

{
  "baseUrl": "https://username.github.io/repo-name"
}

Cloud Storage Platforms

AWS S3 + CloudFront

S3 Bucket Setup

# Install AWS CLI
npm install -g aws-cli

# Configure credentials
aws configure

# Create bucket
aws s3 mb s3://docs.example.com

# Enable static website hosting
aws s3 website s3://docs.example.com --index-document index.html --error-document 404.html

# Upload build
aws s3 sync dist/ s3://docs.example.com --delete

Bucket Policy

{
  "Version": "2012-10-17",
  "Statement": [{
    "Sid": "PublicReadGetObject",
    "Effect": "Allow",
    "Principal": "*",
    "Action": "s3:GetObject",
    "Resource": "arn:aws:s3:::docs.example.com/*"
  }]
}

CloudFront Distribution

1. Go to CloudFront console
2. Create distribution
3. Origin: Your S3 bucket
4. Default root object: index.html
5. Enable HTTPS
6. Deploy

Google Cloud Storage

# Install gcloud CLI
# https://cloud.google.com/sdk/docs/install

# Authenticate
gcloud auth login

# Create bucket
gsutil mb gs://docs.example.com

# Configure for web hosting
gsutil web set -m index.html -e 404.html gs://docs.example.com

# Upload files
gsutil -m rsync -r -d dist/ gs://docs.example.com

# Make public
gsutil iam ch allUsers:objectViewer gs://docs.example.com

Traditional Hosting

Shared Hosting / cPanel

1. Build locally: npm run build
2. Connect via FTP/SFTP
3. Upload contents of dist/ to public_html/ or www/
4. Ensure .htaccess is configured for clean URLs

.htaccess for clean URLs:

RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ /index.html [L]

VPS / Dedicated Server

With Nginx

1. Build and upload files
2. Configure Nginx:

server {
    listen 80;
    server_name docs.example.com;
    root /var/www/docs;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    # Enable gzip compression
    gzip on;
    gzip_types text/html text/css application/javascript application/json;
}

3. Reload Nginx:

sudo nginx -t
sudo systemctl reload nginx

With Apache

    ServerName docs.example.com
    DocumentRoot /var/www/docs

    
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    

    # Enable compression
    AddOutputFilterByType DEFLATE text/html text/css application/javascript

Docker Deployment

Dockerfile

FROM nginx:alpine

# Copy built files
COPY dist/ /usr/share/nginx/html/

# Copy nginx configuration
COPY nginx.conf /etc/nginx/conf.d/default.conf

EXPOSE 80

CMD ["nginx", "-g", "daemon off;"]

nginx.conf

server {
    listen 80;
    root /usr/share/nginx/html;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    gzip on;
    gzip_types text/html text/css application/javascript;
}

Build and Run

# Build image
docker build -t my-docs .

# Run container
docker run -d -p 80:80 my-docs

Continuous Deployment

Automated Deployment Workflow

# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Build
        run: npm run build
      
      - name: Deploy to Netlify
        uses: nwtgck/actions-netlify@v2
        with:
          publish-dir: './dist'
          production-deploy: true
        env:
          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}

Custom Domain Setup

DNS Configuration

Point your domain to your hosting platform:

A Record (IP address):

Type: A
Name: @
Value: 192.0.2.1

CNAME Record (hostname):

Type: CNAME
Name: docs
Value: your-site.netlify.app

SSL Certificate

Most modern platforms provide free SSL:

• Netlify/Vercel: Automatic HTTPS
• Cloudflare: Free SSL with CDN
• Let's Encrypt: Free SSL for self-hosted

Let's Encrypt with Certbot

# Install certbot
sudo apt install certbot python3-certbot-nginx

# Get certificate
sudo certbot --nginx -d docs.example.com

# Auto-renewal
sudo certbot renew --dry-run

Performance Optimization

Enable Compression

Nginx:

gzip on;
gzip_comp_level 6;
gzip_types text/html text/css application/javascript application/json;

Apache:

    AddOutputFilterByType DEFLATE text/html text/css application/javascript

Cache Headers

Nginx:

location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

Apache:

    ExpiresActive On
    ExpiresByType text/html "access plus 1 hour"
    ExpiresByType text/css "access plus 1 year"
    ExpiresByType application/javascript "access plus 1 year"

CDN Integration

Add your site to a CDN for global performance:

• Cloudflare: Free tier available
• AWS CloudFront: Pay as you go
• Fastly: Enterprise CDN

Monitoring and Analytics

Google Analytics

Add to config/site.json:

{
  "analytics": {
    "googleAnalytics": "G-XXXXXXXXXX"
  }
}

Plausible Analytics

Privacy-friendly alternative:

{
  "analytics": {
    "plausible": {
      "domain": "docs.example.com"
    }
  }
}

Monitoring Tools

• Uptime Robot: Monitor site availability
• Google Search Console: SEO monitoring
• Lighthouse CI: Performance monitoring

Troubleshooting

404 Errors on Refresh

Solution: Configure server to serve index.html for all routes.

Netlify: Add _redirects file:

/*    /index.html   200

Vercel: Already handled by framework preset

Nginx: Use try_files directive (see above)

Assets Not Loading

• Check baseUrl in config/site.json
• Verify asset paths start with /
• Clear CDN cache
• Check browser console for errors

Slow Load Times

• Enable compression (gzip/brotli)
• Use CDN
• Optimize images
• Enable caching headers
• Minify assets (should be automatic)

Search Not Working

• Verify dist/pagefind/ directory exists
• Check search index was generated during build
• Ensure JavaScript is not blocked
• Check browser console for errors

Post-Deployment

Verification Checklist

• [ ] Site loads at custom domain
• [ ] HTTPS is working
• [ ] All pages are accessible
• [ ] Search functions correctly
• [ ] Images and assets load
• [ ] Mobile responsive
• [ ] Performance is good (run Lighthouse)

Submit to Search Engines

Google Search Console:

1. Add property
2. Verify ownership
3. Submit sitemap: https://docs.example.com/sitemap.xml

Bing Webmaster Tools:

1. Add site
2. Verify ownership
3. Submit sitemap

Monitor Performance

• Set up uptime monitoring
• Track analytics
• Monitor search console
• Check for broken links regularly

Best Practices

Documentation Deployment

1. Test thoroughly before deploying
2. Use version control for all changes
3. Automate deployments via CI/CD
4. Enable HTTPS always
5. Use CDN for global users
6. Monitor uptime and performance
7. Keep dependencies updated

Rollback Strategy

Always be able to rollback:

Git-based:

# Revert last commit
git revert HEAD
git push

# Deployment happens automatically

Manual:

• Keep previous dist/ folder as backup
• Upload previous version if needed

Next Steps

After launching:

1. Monitor site performance and uptime
2. Gather user feedback
3. Iterate on content
4. Keep documentation up to date
5. Promote your documentation