Static Site Generation

How to run SvelDocs as a prerendered static site.

When To Use SSG (Static Site Generation)

Use static site generation when all of your docs are public and can be built ahead of time. This is the current default provided from this project.

The benefits are straightforward:

  • Simple, typically free hosting
  • Fast page loads
  • CDN-friendly output
  • No runtime server requirements

Configuration

The adapter is configured in svelte.config.js. The static adapter is the default.

svelte.config.js
// import adapter from '@sveltejs/adapter-auto';
import adapterStatic from '@sveltejs/adapter-static';
 
const config = {
	...
	kit: {
		adapter: adapterStatic({
			fallback: '404.html'
		}),
		// adapter: adapter()
		...
	}
};
.js

The static adapter generates .html and .md files instead of running a server for each request.

Base Path Support

This project already supports a deployment base path in svelte.config.js for hosting on websites such as GitHub:

svelte.config.js
const config = {
	...
	kit: {
		...
		paths: {
			base: process.argv.includes('dev') ? '' : process.env.BASE_PATH
		},
		...
	}
};
.js

This is useful when deploying the static site under a subpath such as your-username.github.io instead of the domain root.

GitHub Pages

This project includes a GitHub Pages deployment workflow. You can remove it if you use a different host.

.github/workflows/deploy.yml
name: Deploy to GitHub Pages
 
on:
  push:
    branches: 'main'
 
jobs:
  build_site:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
 
      - name: Install Bun
        uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest
 
      - name: Install dependencies
        run: bun install
 
      - name: Validate
        run: bun test && bun run check && bun run lint
 
      - name: Build
        env:
          BASE_PATH: '/${{ github.event.repository.name }}'
        run: bun run build
 
      - name: Upload Artifacts
        uses: actions/upload-pages-artifact@v3
        with:
          path: 'build/'
 
  deploy:
    needs: build_site
    runs-on: ubuntu-latest
 
    permissions:
      pages: write
      id-token: write
 
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
 
    steps:
      - name: Deploy
        id: deployment
        uses: actions/deploy-pages@v4
.yml