GitHub

From Publish Legacy

DEPRECATION NOTICE: This is documentation related to legacy publishing. For the latest guidance, reference the current publishing documentation.

This guide describes publishing to GitHub using GitHub Actions

Pre-requisite

you already have your workspace under version control and a repository on GitHub
you have configured your dendron.yml for publication

Checklist

Setup

Checkout the pages branch and push it to GitHub

git checkout -b pages
git push origin pages

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

Create a package.json at the root of your workspace

NOTE: by default, we adopt the Creative Commons License but you might want to change this depending on your use case

{
    "scripts": {
        "dendron-cli": "dendron-cli"
    },
    "license": "CC BY 4.0",
    "devDependencies": {
        "@dendronhq/dendron-cli": "*",
        "@dendronhq/dendron-11ty-legacy": "*"
    }
}

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.

Add the .nojekyll file at the base of your repo

touch .nojekyll

Commit these changes and then push your main branch

git add .
git commit -m "add publishing via gh-action"
git push

Update your GitHub Pages setting to build GitHub Pages from the pages branch and using the root folder.

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

Credit to Luke Carrier for his initial contributions to publishing Dendron with GitHub.

Backlinks