Skip to content
girok-md

Deployment

girok-md can be deployed to GitHub Pages, Vercel, Netlify, or any static hosting platform.

  1. Create the workflow file

    Create .github/workflows/deploy.yml:

    .github/workflows/deploy.yml
    name: Deploy to GitHub Pages
    

    on:
      push:
        branches: [main]
      workflow_dispatch:
    

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

    concurrency:
      group: pages
      cancel-in-progress: false
    

    jobs:
      build:
        runs-on: ubuntu-latest
        steps:
          - name: Checkout
            uses: actions/checkout@v4
    

          - name: Setup Node
            uses: actions/setup-node@v4
            with:
              node-version: 20
              cache: npm
    

          - name: Install dependencies
            run: npm ci
    

          - name: Build
            run: npm run build
    

          - name: Upload artifact
            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:
          - name: Deploy to GitHub Pages
            id: deployment
            uses: actions/deploy-pages@v4

  2. Configure GitHub Pages

    1. Go to your repository’s Settings → Pages
    2. Under Source, select GitHub Actions
    3. Save the settings

  3. Push to deploy

    Terminal window
    git add .
    git commit -m "Add GitHub Pages deployment"
    git push

    Your site will be available at https://username.github.io/repository-name

Custom Domain

To use a custom domain:

  1. Create a CNAME file in public/:

    public/CNAME
    your-domain.com

  2. Update setting.toml:

    setting.toml
    site_url = "https://your-domain.com"

  3. Configure DNS with your domain provider

Other Platforms

  1. Import your repository on Vercel
  2. Configure build settings:
    • Framework Preset: Astro
    • Build Command: npm run build
    • Output Directory: dist
  3. Deploy

Docker

Run your blog in a Docker container. Just mount your markdown folder and setting.toml — the container handles syncing, building, and serving automatically.

Prerequisites

  • Docker installed on your machine

Quick Start

  1. Set source_root_path in setting.toml

    The container mounts your markdown folder to /source, so the path must match:

    setting.toml
    source_root_path = "/source"

  2. Build the Docker image

    Terminal window
    docker build -t girok-md .

  3. Run the container

    Terminal window
    docker run -d -p 8080:8080 \
      -v /path/to/your/markdown-folder:/source:ro \
      -v ./setting.toml:/app/setting.toml:ro \
      girok-md
    • Replace /path/to/your/markdown-folder with the actual path to your markdown files
    • :ro means read-only — your original files are never modified
    • The blog will be available at http://localhost:8080

Using Docker Compose

For a simpler workflow, edit docker-compose.yml and run with a single command:

docker-compose.yml
services:
  blog:
    build: .
    ports:
      - "8080:8080"
    volumes:
      - /path/to/your/markdown-folder:/source:ro
      - ./setting.toml:/app/setting.toml:ro
Terminal window
docker compose up -d

How It Works

The container runs through three steps on startup:

  1. Sync — copies markdown files from /source into the project
  2. Build — generates static HTML pages and search index
  3. Serve — starts Nginx to serve the built site on port 8080

Rebuilding After Content Changes

The container builds the site once at startup. To pick up new or updated markdown files, restart the container:

Terminal window
docker compose down && docker compose up -d

Manual Deployment

Build your site locally and upload to any static host:

Terminal window
npm run build

The built site will be in the dist/ folder:

  • Directorydist/
    • index.html
    • Directoryposts/
      • Directorymy-first-post/
        • index.html
    • Directorytags/
      • …
    • Directorypagefind/
      • …
    • Directoryassets/
      • …
    • Directory_astro/
      • …

Upload the contents of dist/ to your web server.

Build Configuration

Base Path

If deploying to a subdirectory (e.g., username.github.io/blog), update astro.config.mjs:

astro.config.mjs
export default defineConfig({
  site: 'https://username.github.io',
  base: '/blog',
  // ...
});

Environment Variables

For production builds, you can use environment variables:

Terminal window
PUBLIC_SITE_URL=https://your-site.com npm run build