Deployment

Deployment

PutOut generates a static site in the dist/ directory. It can be hosted on any static hosting platform.

Netlify (Recommended)

One-Click Deploy

This creates a new repo in your GitHub account, connects it to Netlify, and deploys automatically.

Manual Setup

1. Push your project to GitHub.

2. Create a new site on Netlify and connect your GitHub repository.

3. Build settings are pre-configured in netlify.toml:

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

4. Netlify will automatically build and deploy on every push.

Custom Domain

1. In Netlify, go to Site settings → Domain management → Add custom domain

2. Enter your domain (e.g. mybook.com)

3. Follow Netlify's instructions to update your DNS records (usually adding a CNAME or A record)

4. Netlify automatically provisions an SSL certificate — your site will be available at https://yourdomain.com

5. Important: Update url in src/_data/site.js to match your custom domain, then push the change:

   url: "https://mybook.com",

What's Pre-Configured

The included netlify.toml sets up:

• Build command: npm run build (site + styles + PDF/EPUB)
• Publish directory: dist/
• 404 handling: Redirects unknown routes to /404.html with a 404 status

Vercel

1. Import your GitHub repo on Vercel.
2. Configure the build settings:
   • Build command: npm run build
   • Output directory: dist
3. Click Deploy. Vercel will build and deploy automatically on every push.

For a custom domain, add it in Vercel's project settings under Domains and update your DNS records. Don't forget to update url in site.js to match.

GitHub Pages

You can deploy to GitHub Pages using GitHub Actions. Add this workflow file to your repository:

1. 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@v4
   
         - uses: actions/setup-node@v4
           with:
             node-version: 20
   
         - run: npm ci
   
         # Install Chromium dependencies for PDF generation
         - run: sudo apt-get update && sudo apt-get install -y chromium-browser
   
         - run: npm run build
   
         - uses: actions/upload-pages-artifact@v3
           with:
             path: dist
   
     deploy:
       needs: build
       runs-on: ubuntu-latest
       environment:
         name: github-pages
         url: ${{ steps.deployment.outputs.page_url }}
       steps:
         - id: deployment
           uses: actions/deploy-pages@v4

2. In your GitHub repo settings, go to Pages and set the source to GitHub Actions.

3. Update url in site.js to your GitHub Pages URL:

   url: "https://yourusername.github.io/your-repo-name",

4. Push the workflow file. GitHub will build and deploy automatically.

Note: The workflow includes Chromium installation for PDF generation. If you don't need PDF/EPUB, you can remove the apt-get line.

Cloudflare Pages

1. Connect your repo on Cloudflare Pages.
2. Set build command to npm run build and output directory to dist.

Self-Hosting

Build locally and upload the dist/ folder to any web server:

npm run build
# Upload dist/ to your server

After Deploying

Once your site is live, take these steps:

1. Update your site URL

Make sure url in src/_data/site.js is set to your actual domain. This is critical for your sitemap, social sharing previews, and search engine indexing:

url: "https://mybook.com",

2. Test social sharing

Paste one of your page URLs into these tools to verify the preview looks correct:

• Twitter Card Validator
• Facebook Sharing Debugger

You should see your book title, description, and cover image.

3. Verify your sitemap

Visit https://yourdomain.com/sitemap.xml in a browser to confirm it lists all your pages with the correct URLs.

4. Submit to search engines (optional)

Submit your sitemap URL to Google Search Console and Bing Webmaster Tools to speed up indexing.

Updating the Template

If you created your site using the "Use this template" button, you can pull updates from the original repo:

# Add the template as a remote (once)
git remote add template https://github.com/deepakness/putout.git

# Fetch and merge updates
git fetch template
git merge template/main --allow-unrelated-histories

# Resolve any conflicts, then push
git add .
git commit -m "Merged updates from template"
git push origin main

Related

• Configuration — Setting your URL and other options
• SEO and Structured Data — How your URL affects SEO
• PDF and EPUB — CI setup for PDF generation