Article

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

Generate documentation to a docs folder:
```
docc-static generate --output ./docs
```
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

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:

Generate documentation locally
Drag the output folder onto https://app.netlify.com/drop

Continuous Deployment

See CI/CD Integration for automated Netlify deployment.

AWS S3 + CloudFront

Create an S3 Bucket

Create a bucket with static website hosting enabled
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:

Create a CloudFront distribution pointing to your S3 bucket
Set the default root object to index.html
Configure error pages to redirect 404s to /index.html (for client-side routing)

Generic Static Servers

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.