isite

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/

Installation

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

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
  • default theme: AstroPaper
  • clones the theme project and generates standard blog posts with 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. Astro uses the upstream AstroPaper project rather than an isite-specific page implementation. Issues are written to src/content/posts/issue-<number>.md; reactions and comments are ordinary Markdown sections, so they remain portable theme content.

Like the Zola engine, Astro accepts --theme and --theme-repo. The selected repository must be an AstroPaper-compatible theme or fork because Astro does not define a common theme interface. The output directory may be empty or an existing compatible project; subsequent runs refresh only issue-*.md and preserve other posts.

Use --theme-revision to pin the theme checkout to a branch, tag, or commit. The built-in Zola theme Even defaults to terav2. AstroPaper and custom themes use the repository's default branch unless a revision is supplied.

isite generate --engine astro \
  --theme my-paper \
  --theme-repo owner/my-astro-paper-fork \
  --theme-revision v2.0.0

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.3.2
      ZOLA_VERSION: v0.23.3
      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-gnu*' -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>

For Astro, use an AstroPaper-compatible repository and add --engine astro.

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