isite

Convert GitHub issues to a website.

Examples

• https://github.com/kemingy/withcode ➡️ https://kemingy.github.io/withcode/
• https://github.com/yihong0618/gitblog ➡️ https://blog.yihong0618.me/

Usage

isite generate --help

After generating the Markdown based documents, you can build the website with the following engines.

Engines

• zola
  • default theme: Even, modified to support comments and reactions
• Astro
  • generates a complete Astro project with issue pages, tags, comments, reactions, and optional RSS/KaTeX support
• hugo

Astro

isite generate --engine astro --base-url https://example.github.io/repository
cd output
npm install
npm run build

The static site is written to output/dist. The --theme and --theme-repo flags are Zola-only because Astro themes are complete projects rather than portable theme directories.

When a repository already has a config.toml, Astro reuses extra.even_title and extra.even_menu by default. This preserves existing custom navigation while generating compatible /issue-<number>/, /tags/<label>/, and paginated /page/<number>/ routes. Use --config <path> to select a different file or --config '' to disable this compatibility behavior.

Installation

• GitHub Releases: download the pre-built binaries from the releases page.
• Docker Image: docker pull ghcr.io/kemingy/isite

GitHub Actions

Important

Please remember to enable the GitHub Pages with GitHub Actions as the source.

You can audit and apply the following GitHub Actions workflow to deploy the static content generated by isite to GitHub Pages.

name: Deploy static content to Pages

on:
  issues:
    types:
      - opened
      - edited
      - closed
      - reopened
      - labeled
      - unlabeled
  issue_comment:
    types:
      - created
      - edited
      - deleted
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: ${{ github.workflow }}
  cancel-in-progress: true

jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    env:
      GH_TOKEN: ${{ github.token }}
      # bump the versions here
      ISITE_VERSION: v0.2.6
      ZOLA_VERSION: v0.20.0
      USER: ${{ github.repository_owner }}
      REPO: ${{ github.event.repository.name }}
      # change this to your custom domain name
      BASE_URL: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}
    steps:
      - name: Checkout
        uses: actions/checkout@v6
      - name: Generate markdown
        run: |
          gh release download $ISITE_VERSION --repo kemingy/isite -p '*linux_amd64*' -O- | tar -xz -C /tmp && mv /tmp/isite /usr/local/bin
          isite generate --user $USER --repo $REPO
          gh release download $ZOLA_VERSION --repo getzola/zola -p '*x86_64-unknown-linux*' -O- | tar -xz -C /tmp && mv /tmp/zola /usr/local/bin
          cd output && zola build --base-url $BASE_URL
      - name: Setup Pages
        uses: actions/configure-pages@v5
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v4
        with:
          path: 'output/public'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

The workflow above builds with Zola. To deploy the Astro engine instead, use these generation/build steps and upload output/dist:

      - name: Generate Astro project
        run: |
          gh release download $ISITE_VERSION --repo kemingy/isite -p '*linux_amd64*' -O- | tar -xz -C /tmp && mv /tmp/isite /usr/local/bin
          isite generate --engine astro --user $USER --repo $REPO --base-url $BASE_URL
      - name: Build Astro site
        run: |
          npm install --prefix output
          npm run build --prefix output
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v4
        with:
          path: 'output/dist'

Customization

Domain name

Change the BASE_URL in the GitHub Actions workflow to your custom domain name.

Other themes

isite generate --theme <theme_name> --theme-repo <user/repo>

Backup Markdown files to the Repo

- name: backup markdown files
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: |
    git config user.name "GitHub Actions Bot"
    git config user.email "github-actions@users.noreply.github.com"
    git checkout -b backup
    git add output/content
    git commit -m "Backup markdown files"
    git push --force origin backup