Github

This guide describes publishing to github using github actions

Pre-requisite

Checklist

  • create pages branch
  • enable github pages on pages branch
  • have package.json
  • create github action
  • enable actions on your repo
  • add .nojekyll to the root of your repo
  • configure your dendron.yml
  • link cname with github pages
  • enforce https on your page

Setup

  1. Checkout the pages branch and push it to github
git checkout -b pages
git push origin pages
  1. Switch back to your original branch
  • NOTE: if you are using old versions of github, this command will be git checkout master
git checkout main
  1. Create a package.json at the root of your workspace
{
    "scripts": {
        "dendron-cli": "dendron-cli"
    },
    "license": "CC BY 4.0",
    "devDependencies": {
        "@dendronhq/dendron-cli": "*",
        "@dendronhq/dendron-11ty-legacy": "*"
    }
}
  1. Create the workflow .github/workflows/dendron-action.yml:
  • create the workflow
mkdir -p .github/workflows
touch .github/workflows/dendron-action.yml
  • file contents
name: Dendron

on:
    push:
        branches:
            - main

jobs:
    build:
        runs-on: ubuntu-latest
        steps:
            - name: Checkout source
              uses: actions/checkout@v2

            - name: Install npm dependencies
              run: npm install

            - name: Build pod
              run: npm run dendron-cli --buildSiteV2 --wsRoot .  --stage prod

            - 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: "dendron.so" # UPDATE WITH DOMAIN NAME

Make sure to update the cname: "dendron.so" value above with your own domain name.

  1. Add the .nojekyll file at the base of your repo
touch .nojekyll
  1. Commit these changes and then push your main branch
git add .
git commit -m "add publishing via gh-action"
git push
  1. Update your github pages setting to build github pages from the pages branch and using the root folder.

  1. Github actions will update your page every time you push. You might have to add a change and push before your changes will show up. You can verify that your action is running by clicking on the actions tab in github.
  • NOTE: depending on your account settings, you might need to enable github first

Lookup