Skip Navigation
ArticleArticle

Deploying Documentation to Servers

Host your generated documentation on web servers and CDNs.

Overview

Documentation generated by docc-static is pure HTML/CSS and can be hosted on any static file server. This guide covers deployment to common hosting platforms.

GitHub Pages

GitHub Pages is a free hosting option for public repositories.

Manual Deployment

  1. Generate documentation to a docs folder:

    docc-static generate --output ./docs
    
  2. Configure your repository to serve from the docs folder:

    • Go to Settings > Pages

    • Set Source to “Deploy from a branch”

    • Select your branch and /docs folder

    • Click Save

  3. Commit and push the docs folder:

    git add docs
    git commit -m "Update documentation"
    git push
    

Your documentation will be available at https://username.github.io/repository/.

Using a Custom Domain

Add a CNAME file to your docs folder:

echo "docs.example.com" > ./docs/CNAME

Then configure your DNS to point to GitHub Pages.

GitLab Pages

GitLab Pages requires a .gitlab-ci.yml file. See CI/CD Integration for a complete example.

The key requirement is that your output must be in a public directory:

docc-static generate --output public

Netlify

Drag and Drop

The simplest method:

  1. Generate documentation locally

  2. Drag the output folder onto Netlify Drop

Continuous Deployment

See CI/CD Integration for automated Netlify deployment.

AWS S3 + CloudFront

Create an S3 Bucket

  1. Create a bucket with static website hosting enabled

  2. Configure public access (or use CloudFront for private buckets)

Upload Documentation

Using the AWS CLI:

docc-static generate --output ./docs

aws s3 sync ./docs s3://your-bucket-name \
    --delete \
    --cache-control "max-age=3600"

CloudFront Distribution

For HTTPS and better performance:

  1. Create a CloudFront distribution pointing to your S3 bucket

  2. Set the default root object to index.html

  3. Configure error pages to redirect 404s to /index.html (for client-side routing)

Generic Static Servers

Documentation pages show the navigation sidebar by embedding sidebar.html from the root of the output directory in a frame. If your server adds security headers, allow pages to be framed by the same site, for example with X-Frame-Options: SAMEORIGIN or Content-Security-Policy: frame-ancestors 'self' rather than DENY or 'none'.

Nginx

Example Nginx configuration:

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

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

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

Apache

Example .htaccess:

DirectoryIndex index.html
Options -Indexes

# Enable compression
<IfModule mod_deflate.c>
    AddOutputFilterByType DEFLATE text/html text/css application/javascript
</IfModule>

# Cache static assets
<IfModule mod_expires.c>
    ExpiresActive On
    ExpiresByType text/css "access plus 1 week"
    ExpiresByType application/javascript "access plus 1 week"
</IfModule>

Caddy

Example Caddyfile:

docs.example.com {
    root * /var/www/documentation
    file_server
    try_files {path} {path}/index.html
    encode gzip
}

Docker

Create a simple Dockerfile to serve documentation:

FROM nginx:alpine
COPY docs/ /usr/share/nginx/html/
EXPOSE 80

Build and run:

docc-static generate --output ./docs
docker build -t my-docs .
docker run -p 8080:80 my-docs

Optimisation Tips

Enable Compression

The generated HTML and CSS compress well. Enable gzip or brotli on your server.

Set Cache Headers

Static documentation rarely changes. Use aggressive caching:

  • HTML files: 1 hour to 1 day

  • CSS/JS files: 1 week to 1 month

  • Images: 1 month

Use a CDN

For global audiences, serve through a CDN like:

  • CloudFlare

  • AWS CloudFront

  • Fastly

  • Bunny CDN

Preload Key Resources

The generated HTML includes proper resource hints, but you can add custom preload headers at the server level for even faster loading.

See Also