Try to create a base new IPython website from scratch

Author: Carreau

.env.example

@@ -0,0 +1,5 @@
+# GitHub Personal Access Token (optional)
+# Get one at: https://github.com/settings/tokens
+# Increases API rate limit from 60/hour to 5000/hour
+# Usage: Create a .env file and add: GITHUB_TOKEN=your_token_here
+GITHUB_TOKEN=

.github/workflows/deploy-ipython-github-com.yml

@@ -0,0 +1,49 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [ main ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      
+      - name: Install Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      
+      - name: Install dependencies
+        run: npm ci
+      
+      - name: Build Astro site
+        run: npm run build
+        env:
+          BASE_PATH: ""
+          GITHUB_REPOSITORY_OWNER: ipython
+      
+      - 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

.github/workflows/deploy.yml

@@ -0,0 +1,68 @@
+name: Deploy to GitHub Pages
+
+on:
+  # Trigger the workflow every time you push to the `main` branch
+  push:
+    branches: [ main ]
+  # Allows you to run this workflow manually from the Actions tab on GitHub.
+  workflow_dispatch:
+
+# Allow this job to clone the repo and create a page deployment
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout your repository using git
+        uses: actions/checkout@v4
+      
+      - name: Install Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      
+      - name: Install dependencies
+        run: npm ci
+      
+      - name: Determine base path
+        id: base_path
+        run: |
+          # If BASE_PATH secret is set, use it
+          # Otherwise, if repo name matches owner (username.github.io), use root
+          # Otherwise, use /repo-name
+          if [ -n "${{ secrets.BASE_PATH }}" ]; then
+            echo "base_path=${{ secrets.BASE_PATH }}" >> $GITHUB_OUTPUT
+          elif [ "${{ github.repository }}" == "${{ github.repository_owner }}/${{ github.repository_owner }}.github.io" ]; then
+            echo "base_path=" >> $GITHUB_OUTPUT
+          else
+            echo "base_path=/${{ github.event.repository.name }}" >> $GITHUB_OUTPUT
+          fi
+      
+      - name: Build Astro site
+        run: npm run build
+        env:
+          BASE_PATH: ${{ steps.base_path.outputs.base_path }}
+          GITHUB_REPOSITORY_OWNER: ${{ github.repository_owner }}
+          # If you have other environment variables, set them here
+          # GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      
+      - 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

.gitignore

@@ -0,0 +1,3 @@
+dist
+node_modules
+.env

CNAME

@@ -0,0 +1 @@
+ipython.org

DEPLOYMENT.md

@@ -0,0 +1,56 @@
+# GitHub Pages Deployment
+
+This repository is configured to automatically deploy to GitHub Pages at `https://ipython.github.io` (or `https://ipython.github.com` which still works).
+
+## Setup Instructions
+
+### 1. Enable GitHub Pages
+
+1. Go to your repository Settings → Pages
+   - Or visit: `https://github.com/ipython/[this-repo]/settings/pages`
+2. Under "Source", select **"GitHub Actions"** (not "Deploy from a branch")
+3. Save the settings
+
+### 2. Deploy
+
+The workflow will automatically run on every push to the `main` branch. You can also manually trigger it:
+
+1. Go to Actions tab
+2. Select "Deploy to GitHub Pages" workflow
+3. Click "Run workflow" → "Run workflow"
+
+## How It Works
+
+The deployment workflow:
+
+1. **Builds the site** from the `main` branch
+2. **Uploads** the built files as an artifact
+3. **Deploys** to GitHub Pages (which serves from the `gh-pages` branch automatically)
+4. Makes the site available at `https://ipython.github.io/[repo-name]` or `https://ipython.github.com/[repo-name]`
+
+## Configuration
+
+The build uses these environment variables:
+- `BASE_PATH`: Set to empty string for root domain deployment
+- `GITHUB_REPOSITORY_OWNER`: Set to `ipython` for correct asset paths
+
+These are set automatically in the workflow.
+
+## Troubleshooting
+
+### "Permission denied" errors
+
+- Ensure GitHub Pages is enabled in repository settings
+- Check that the workflow has the correct permissions (should be automatic)
+
+### Build succeeds but site doesn't update
+
+- Check the Actions logs for the deploy step
+- Wait a few minutes for GitHub Pages to rebuild
+- Verify the Pages source is set to "GitHub Actions" not a branch
+
+### Site not accessible
+
+- Check repository visibility (public repos work automatically)
+- Verify the repository name matches the expected GitHub Pages URL pattern
+- For organization repos, ensure Pages is enabled at the organization level if needed