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
• hugo

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.2
      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@v4
      - name: Generate markdown
        run: |
          gh release download $ISITE_VERSION --repo kemingy/isite -p '*Linux_x86_64*' -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@v3
        with:
          path: 'output/public'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

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