GitHub Pages

Summary

You can publish your notes using Dendron Next.js Publishing and GitHub Pages.

Before continuing: we do not recommend this path for publishing. If possible, visit GitHub Pages publishing with GitHub Actions for generating and publishing your website, instead!

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 means that you don't need to continously make messy commits full of autogenerated files anymore. You won't need to version your published site files, or pull down to every system you use to write notes, since we only care about versioning the notes themselves.

Prerequisites

  • You have Dendron CLI installed (version 0.70.0 or greater)

Example Deployments

You can see deployed examples of these instructions in the following repositories.

Steps - Setup GitHub

Create a GitHub repo

Follow the instructions in the GitHub Pages documentation to create a repository named {username}.github.io where {username} is your username on GitHub.

Add your notes

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

Turn on GitHub Pages

Go to settings

Go down to GitHub Pages and select the main branch

Select the docs folder and click save.

Steps - Setup Dendron

Setup Dendron Next.js Publishing

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

    npm init -y 
    npm install @dendronhq/dendron-cli@latest
    

  3. Initialize Dendron Next.js publishing

    1. Update .gitignore
      echo .next >> .gitignore
      
    2. Clone the Next.js repository and install dependencies
      npx dendron publish init
      

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 site:

...
site:
    ...
    siteUrl: {SITE_URL}

GitHub Pages URLs

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

  • NOTE: Some special considerations for the SITE_URL
    • if your REPO_NAME is the same as your GITHUB_USERNAME
      • set SITE_URL to https://{GITHUB_USERNAME}.github.io
    • if your REPO_NAME is anything else
      - set `SITE_URL` to `https://{GITHUB_USERNAME}.github.io`
      - set `assetsPrefix`to `/REPO_NAME`
      

Examples

  • publishing the repo named kevinslin.github.io
site:
    siteUrl: https://kevinslin.github.io
  • publishing the repo named dendron-publish-sample
site:
    assetsPrefix: /dendron-publish-sample
    siteUrl: https://kevinslin.github.io

Build and preview your notes

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

Publish your notes

  • NOTE: we're running export with the GitHub target
npx dendron publish export --target github

Deploy your changes

git add .
git commit -m "Dendron page update"
git push

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.

Updating dendron and published content

One major reason that GitHub Pages publishing with GitHub Actions is preferred, as opposed to this path, is that the GitHub Actions can automatically manage updates to your website.

If not using GitHub Actions, the following needs to be done whenever you'd like to publish a new version of your website.

rm -rf docs
rm -rf .next
rm -rf node_modules
rm -rf package*.json
npm install @dendronhq/dendron-cli@latest
npx dendron publish init
npx dendron publish export --target github
git add .
git commit -m "Dendron page update"
git push

Congratulations, you just published your first note 🌱


Backlinks