GitHub Pages with GitHub Actions

Summary

Publishing Dendron using GitHub Actions, by using GitHub Actions for GitHub Pages.

Details

GitHub Actions help provide an automated form of publishing where your notes are published whenever a new commit is made to the main branch of your GitHub repository.

The generated site is also written to the pages branch of your repository, which keeps the published site contents separate from your main branch commit history.

Prerequisites

npm init -y

npm install @dendronhq/dendron-cli@latest

Example Deployment

Looking for an easy button?

You can see a deployed example of these instructions in the following repository, which can be used as a template (recommended):

• Dendron on GitHub Pages with GitHub Actions Template: template.publish.github-action
  • Make sure to select Include all branches when creating a new repository from this template.
  • The template, with every update, publishes to this example website

You'll need to change both the siteUrl and assetsPrefix fields in dendron.yml to your own location, unless you are planning to go with a custom domain name

Steps

1. Create a GitHub repo

NOTE: The following directions assume you aren't using the example deployment template which can be autogenerated from the repository. If you are using the template, move forward to Enable GitHub Pages.

Follow the instructions here to create a repository.

2. Setup Publishing

...
publishing:
    ...
    siteUrl: {WEBSITE_URL}

publishing:
    siteUrl: https://kevinslin.github.io

publishing:
    assetsPrefix: /dendron-publish-sample
    siteUrl: https://kevinslin.github.io

npx dendron publish dev

3. Setup GitHub Pages

• Create a pages branch

  git checkout -b pages
  git push -u origin HEAD
  

Enable GitHub Pages

• Turn on GitHub Pages for the pages branch
  • Follow the Choosing a publishing source GitHub documentation with:
    • pages branch
    • / (root) folder

4. Setup GitHub Actions

1. Switch back to your main branch

   git checkout main
   

2. Create a workflow

• mac and linux

  mkdir -p .github/workflows
  touch .github/workflows/publish.yml
  

• windows

  mkdir -p .github/workflows
  New-Item .github/workflows/publish.yml
  

1. Setup workflow

   name: Build Dendron Static Site
   
   on:
     workflow_dispatch: # Enables on-demand/manual triggering
     push:
       branches:
       - main
   
   jobs:
     build:
       runs-on: ubuntu-latest
       steps:
       - name: Checkout source
         uses: actions/checkout@v2
         with:
           fetch-depth: 0
   
       - name: Restore Node modules cache
         uses: actions/cache@v2
         id: node-modules-cache
         with:
           path: |
             node_modules
             .next/*
             !.next/.next/cache
             !.next/.env.*
           key: ${{ runner.os }}-dendronv2-${{ hashFiles('**/yarn.lock', '**/package-lock.json') }}
   
       - name: Install dependencies
         run: yarn
   
       - name: Initialize or pull nextjs template
         run: "(test -d .next) && (echo 'updating dendron next...' && cd .next && git reset --hard && git pull && yarn && cd ..) || (echo 'init dendron next' && yarn dendron publish init)"
   
       - name: Restore Next cache
         uses: actions/cache@v2
         with:
           path: .next/.next/cache
           # Generate a new cache whenever packages or source files change.
           key: ${{ runner.os }}-nextjs-${{ hashFiles('.next/yarn.lock', '.next/package-lock.json') }}-${{ hashFiles('.next/**.[jt]s', '.next/**.[jt]sx') }}
   
       - name: Export notes
         run: yarn dendron publish export --target github --yes
   
       - name: Deploy site
         uses: peaceiris/actions-gh-pages@v3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_branch: pages
           publish_dir: docs/
           force_orphan: true
           #cname: example.com
   

2. Commit your changes

   git add .
   git commit -m "add workflow"
   git push
   

• NOTE: if you are interested in what exactly the github action script is doing, see Action Detail

5. First Deployments

Upgrading

Next Steps

• Review and further customize your Publishing Configurations as needed.
• If you intend for your published site to be publicly viewable, make sure to add it to the awesome-dendron repo so that the community can see your digital garden.

Congratulations, you just published your first note 🌱

1. GH Action Detail