GitHub Pages

Summary

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

Not Recommended

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!

Prerequisites

Install git
Initializes a npm repo at the root of your workspace (where dendron.yml is located)

npm init -y

Install dendron-cli

npm install @dendronhq/dendron-cli@latest

Example Deployments

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

Publish a regular GitHub page

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

Navigate to the root of your workspace (directory with dendron.yml)
Initialize publishing
From Common
Go to text →
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:

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

GitHub Pages URLs

Your WEBSITE_URL for GitHub Pages will be in the following format: https://{GITHUB_USERNAME}.github.io/{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}.github.io in dendron.yml
- if your REPO_NAME is anything else
  - set siteUrl to https://{GITHUB_USERNAME}.github.io in dendron.yml
  - set assetsPrefixto /REPO_NAME in dendron.yml
NOTE: if you want to publish with a custom domain, see Custom Domain Name

Examples

publishing the repo named kevinslin.github.io

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

publishing the repo named dendron-publish-sample

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

Build and preview your notes

From Common

Go to text →

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.

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.

Github First Deployment

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