How to deploy to GitHub Pages

[efemkay]

I read the docs. U noted that it technically should be able to be deployed to most if not any static site host. I'm interested to know how one can deploy to GitHub Pages (i.e. with URL username.github.io).

The deploy to netlify and vercel have its own template from your docs page, which makes it quite straightforward. But I couldn't figure out how to do so with GitHub Pages. Can u share the steps / how to?

Thanks!

[David7ce]

I think you need to use the Digital Garden template which is an 11Ty template and deploy to GitHub. Then activate GitHub Pages and connect the plugin of your Obsidian vault to the GitHub repo.

11Ty is a Static Site Generator

It has three config files one
.GitHub/workflow/build.yml
Netlify.toml
Vercel.json

All of them with the commands for npm:
npm install
npm run build
npm run start

In theory you can run these npm commands locally and push the output website to the Git repo.

But I tried and I couldn't do it, some errors with keys or APIs I don't remember.

[oleeskild]

I looked a bit into it, and got it to work with the following workflow:

name: GH Pages

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:
  build:

    runs-on: ubuntu-22.04

    strategy:
      matrix:
        node-version: [20.x]
        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/

    steps:
      - uses: actions/checkout@v3
      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'
      - run: npm install
      - run: npm run build --if-present

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          publish_dir: ./dist
          github_token: ${{ secrets.GH_TOKEN }}

You will need to add a GH_TOKEN secret to your repo, which should be a github API token having access to your repo. (You can reuse the one you have in your plugin settings)
You will also need to name your repository in github, <username>.github.io. So in your case efemkay.github.io. This is because otherwise the URL will be <username>.github.io/<repositoryname>. This will cause errors when the site tries to get CSS and Javascript from URLs like <username>.github.io/styles/style.css, because they are actually located in <username>.github.io/<repositoryname>/styles/style.css.

Let me know if you get it to work or not!

[zcysxy]

Is it possible to publish at a repo with a different name, i.e., to redirect it to get CSS and JS files from <username>.github.io/<repositoryname>/...?

[David7ce]

This is to autobuild with GitHub. But is it possible to build the template locally with "npm install & nmp run biuld --if-present" and then upload the "dist/" dir to GitHub with git?

I'm interesting in building manually without bots and neither GitHub tokens.

Edit: I have tried in the past but it didn't work, maybe there is a method to achieve that.

[pflenker]

Hi 👋

I got it running with the following action:

name: GH Pages

on:
  push:
    branches:
      - main  # Set a branch name to trigger deployment
  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:      
  pull_request:
permissions:
  contents: read
  pages: write
  id-token: write    
concurrency:
  group: "pages"
  cancel-in-progress: false  
jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '23'
        
      - run: npm install
      - run: npm run build 
      - name: Setup Pages
        uses: actions/configure-pages@v5
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: 'dist'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4
        

no need to set any secret. All I had to do was disable the default action in the repo settings under „private“ and commit to main, then this action deployed the changes correctly.

[foxblock]

Hi,
Based on the work of @mounta11n (#160 (comment)), I created a fork of the template which uses GitHub pages as a method of deployment.

Use this template and follow the steps in the included README: https://github.com/foxblock/digitalgarden_gh-pages
It also includes the steps necessary to embed a comment function into your pages.

Good luck!

[pflenker]

Hi @foxblock ,

your template will likely not fully work with 404 pages. When clicking an invalid link from within the digital garden, it will work just fine, but accessing (yourid).github.io/somegarbage/ will bring up the default 404 from GitHub Pages.
You can fix that by adding the following on top of your src/site/404.njk:

---
permalink: 404.html 
---

[foxblock]

Thanks for the fix, tested and added it to the template!

[raycadle]

Hi, awesome work with the plugin so far! I can't wait to see how much greater it becomes over time.

Had a quick question: would it be possible to deploy to gh-pages without using the .github.io repo?

[raycadle]

No, no, I meant without using the <username>.github.io repo.

I.e. using a different repo but still deploying using github pages. So it would instead be at <username>.github.io/digital-garden, for example.

My bad for not explaining clearly.

[foxblock]

You can use path rewrite rules. (Plugin Settings -> Manage Rewrite Rules)
:digital-garden/ will add the "digital-garden" folder at the beginning of each note's path.
Note however that only the first applicable rewrite rule is applied. Essentially this means you are completely blocking that feature and will not be able to do other path rewrites.

Other than that you can place all your published notes in a digital-garden folder in your vault.

In any case you will always get one extra layer in the file tree as well. Which is not what you might want.

[raycadle]

So this would allow the style.css and Javascript to load properly instead of rendering the page with only text?

I originally used a digital-garden repo but ran into that issue. That's when I read the discussion about it having to be at <username>.github.io and changed it.

[foxblock]

Yes, all of that should work as normal.

[raycadle]

Awesome! Thank you! I'll try it out in a little bit and report back if it doesn't.

Have a good one!