GitHub Pages with GitHub Actions


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


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.


  • Install git
  • Initializes a npm repo at the root of your workspace (where dendron.yml is located)
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):

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


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.

Add your notes

Navigate to your existing Dendron workspace. Follow instructions provided by GitHub to push your workspace to GitHub.

2. Setup Publishing

  1. Navigate to the root of your workspace (directory with dendron.yml)
  2. Initialize publishing

    Run the following command to setup publishing for your vault. This will pull in the nextjs-template which will be used to generated a static website from your notes.

    NOTE: if you are having trouble doing this using powershell, we recommend following these steps using WSL instead

    npx dendron publish init
    # you should see the following output
    🌱 checking if .next directory exists.
    🌱 .next directory does not exist
    🌱 Initializing NextJS template.
    🌱 Successfully cloned.
    🌱 All dependencies installed.

Configure your notes for publication

In order for to build your notes for publication, open the command prompt and type >Dendron: Configure (yaml)

Make the following modification under publishing:

    siteUrl: {WEBSITE_URL}

GitHub Pages URLs

Your WEBSITE_URL for GitHub Pages will be in the following format: https://{GITHUB_USERNAME}{REPO_NAME}/.

  • NOTE: Some special considerations for the WEBSITE_URL

    • if your REPO_NAME is the same as your GITHUB_USERNAME
      • set siteUrl to https://{GITHUB_USERNAME} in dendron.yml
    • if your REPO_NAME is anything else
      • set siteUrl to https://{GITHUB_USERNAME} in dendron.yml
      • set assetsPrefixto /REPO_NAME in dendron.yml
  • NOTE: if you want to publish with a custom domain, see Custom Domain Name


  • publishing the repo named
  • publishing the repo named dendron-publish-sample
    assetsPrefix: /dendron-publish-sample

Build and preview your notes

Run the following to see a local preview of what your site will look like. By default, Dendron will publish all the notes in your given vault.

  • This command launches a development server which previews how your published website will look like. Visit http://localhost:3000 to access your site.
  • Enter CTRL-C on the terminal to exit the preview
npx dendron publish dev

NOTE: if you only want to publish a particular vault, see the guide here. If you want to publish specific hierarchies, you can do so by modifying siteHierarchies.

3. Setup GitHub Pages

  • Create a pages branch
    git checkout -b pages
    git push -u origin HEAD

Enable GitHub Pages

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
      workflow_dispatch: # Enables on-demand/manual triggering
        - main
        runs-on: ubuntu-latest
        - name: Checkout source
          uses: actions/checkout@v2
            fetch-depth: 0
        - name: Restore Node modules cache
          uses: actions/cache@v2
          id: node-modules-cache
            path: |
            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
            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
            github_token: ${{ secrets.GITHUB_TOKEN }}
            publish_branch: pages
            publish_dir: docs/
            force_orphan: true
  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

The first push will take a bit because Next.js generates a bunch of assets on initial publishing. Subsequent pushes will only commit changes and will be much faster.

You can see the status of your page by going clicking GitHub pages in your GitHub repo.

Since this is your first deployment, it might take a minute before you page shows up.

Github First Deployment


For upgrading CLI, and dendron workspace configurations, make sure to do the following to have the latest and greatest updates in your published site.

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