Deploying to GitHub Pages

Prepare Your Repository

First, ensure your project is properly configured for GitHub Pages deployment.

Repository Settings

1. Navigate to your repository on GitHub
2. Go to Settings → Pages
3. Under Source, select GitHub Actions

Project Structure

Make sure your project structure follows this pattern:

your-repo/
├── .github/
│   └── workflows/
│       └── deploy.yml
├── src/
│   └── YourProject/
│       ├── YourProject.csproj
│       ├── Program.cs
│       └── Content/
├── global.json
└── README.md

Note that we are using a global.json file to specify the .NET SDK version. This ensures consistent builds across different environments, and is used in the GH pages to install the appropriate .NET version.

Configure GitHub Actions Workflow

Create .github/workflows/deploy.yml in your repository root:

name: Build and publish to GitHub Pages
  
on:
  push:
    branches: [ "*" ]
  pull_request:
    branches: [ "main" ]
  
env:
  ASPNETCORE_ENVIRONMENT: Production
  WEBAPP_PATH: ./src/YourProject/
  WEBAPP_CSPROJ: YourProject.csproj
  
permissions:
  contents: read
  pages: write
  id-token: write
  
# Allow only one concurrent deployment
concurrency:
  group: "pages"
  cancel-in-progress: false
  
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
  
      - name: Install .NET
        uses: actions/setup-dotnet@v4
        with:
          global-json-file: global.json
  
      - name: Run webapp and generate static files
        env:
          DOTNET_CLI_TELEMETRY_OPTOUT: true
        run: |
          dotnet build
          dotnet run --project ${{ env.WEBAPP_PATH }}${{env.WEBAPP_CSPROJ}} --configuration Release -- build "/your-repository-name/"

      - name: Setup Pages
        uses: actions/configure-pages@v4
  
      - name: Add .nojekyll file
        run: touch ${{ env.WEBAPP_PATH }}output/.nojekyll
  
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ${{ env.WEBAPP_PATH }}output
  
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    if: (github.event_name == 'push' && github.ref == 'refs/heads/main') || (github.event_name == 'pull_request' && github.event.action == 'closed' && github.event.pull_request.merged == true)
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Key Configuration Points

Variables to Update:

• WEBAPP_PATH: Path to your project directory
• WEBAPP_CSPROJ: Your project file name
• "/your-repository-name/": Your repository name in the build command (for GitHub Pages subdirectory)

Important: Replace your-repository-name and YourProject with your actual values.

Configuring Base URLs

This is one of the most important aspects of GitHub Pages deployment. Understanding BaseUrl is crucial for your site to work correctly.

Why BaseUrl Matters

Local Development vs GitHub Pages:

• Local development: Your site runs at http://localhost:5000/ (root domain)
• GitHub Pages: Your site runs at https://username.github.io/repository-name/ (subdirectory)

Without proper BaseUrl configuration, your site will have broken links, missing CSS, and non-functional navigation when deployed to GitHub Pages.

See the Linking Documents and Media guide for more details on how MyLittleContentEngine handles links.

Update Your Program.cs

For basic usage, you typically don't need to configure anything special in your Program.cs for GitHub Pages deployment. The build command line arguments will handle the BaseUrl automatically.

The BaseUrl is now configured via command line arguments during the build process instead of being hardcoded in your Program.cs.

Set Up GitHub Pages

Enable GitHub Pages

1. Go to your repository Settings
2. Navigate to Pages in the sidebar
3. Under Source, select GitHub Actions
4. Save the settings

Test Your Deployment

Push Your Changes

Commit and push your workflow file:

git add .github/workflows/deploy.yml
git commit -m "Add GitHub Pages deployment workflow"
git push origin main

Monitor the Build

1. Go to the Actions tab in your repository
2. Watch the workflow run
3. Check for any errors in the build process

Verify Deployment

Once the workflow completes:

1. Your site should be available at https://username.github.io/repository-name/
2. Check that all pages load correctly
3. Verify that navigation works properly
4. Test that images and other assets load

Custom Domain (Optional)

To use a custom domain:

Configure DNS

Add a CNAME record pointing to username.github.io:

CNAME  www.yourdomain.com  username.github.io

Update Repository Settings

1. Go to Settings → Pages
2. Enter your custom domain in the Custom domain field
3. GitHub will automatically create a CNAME file in your repository

Update Base URL

Modify your workflow to use your custom domain:

- name: Run webapp and generate static files
  env:
    DOTNET_CLI_TELEMETRY_OPTOUT: true
  run: |
    dotnet build
    dotnet run --project ${{ env.WEBAPP_PATH }}${{env.WEBAPP_CSPROJ}} --configuration Release -- build "/"  # Root path for custom domain