Netlify

Summary

You can publish your notes using Dendron publishing and Netlify.

Prerequisites

  • This assumes you have a Netlify account.

  • 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

Netlify is also compatible with GitLab and BitBucket, when it comes to integrations. Though, this guide will focus on GitHub.

Example Deployment

Looking for a quickstart? Read the Dendron blog post: Share Your Notes Online: Publish Dendron with Netlify and GitHub

You can see a deployed example of these instructions in the following repository, which can be used as a template (recommended):

Create a GitHub repo

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 Netlify URLs.

Follow the instructions here to create a repository. Netlify can publish both private and public repositories, leaving it up to you for the source code to be publicly available for viewing or contributions.

Add your notes

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

Steps - Setup Dendron

Setup Dendron Next.js 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:

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

Netlify URLs

Your SITE_URL for Netlify websites will be in the following format: https://{CUSTOM_NAME}.netlify.app (by default).

CUSTOM_NAME is either an auto-generated name, like brave-curie-671954, or a custom name manually set.

If you decide to go with a custom domain on Netlify, then make sure that siteUrl is configured appropriately:

publishing:
    siteUrl: https://example.com

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.

Publish your notes

We need to now fulfill the prerequisites expected by Netlify.

gitignore

Make sure your .gitignore file contains the following, at a minimum.

node_modules
.dendron.*
build
seeds
.next
docs
.backup

Publishing script

Create dendron-publish-site.sh in the root of your workspace.

The following shell script is meant be executed within a build/deployment pipeline, and will work for websites such as Netlify, GitLab Pages, and others.

#!/usr/bin/env bash
# dendron-publish-site.sh
# This script should exist in the root of your workspace

# Remove docs directory if present
rm -rf docs

# Uncomment if wishing to remove cache
# Recommended: Leave cache alone to increase speed of deployments
#rm -rf .next
#rm -rf node_modules

# Install latest version of Dendron
# yarn add @dendronhq/dendron-cli@latest
# OPTIONALLY
# Install version of Dendron from yarn.lock in workspace root
# To use:
# Uncomment the next line, and comment out the other `yarn install ...` line
yarn

# Update Dendron Next.js if needed
(test -d .next) && (echo 'updating dendron next...' && cd .next && git reset --hard && git pull && yarn && cd ..) || (echo 'init dendron next' && yarn dendron publish init)

# Generate static site with nextjs
yarn dendron publish export

# Move generated website to docs directory in workspace root
mv .next/out docs

netlify.toml

For this guide, we are using the file-based configuration that references a netlify.toml file in the root of our repo.

This configuration expects the dendron-publish-site.sh script to exist in the root of your Dendron workspace.

# Minimal config
[build]
  # Directory that contains the deploy-ready HTML files and assets generated by
  # the build. This is relative to the base directory if one has been set, or the
  # root directory if a base has not been set
  publish = "docs"

  # Build command
  # Use the build script at root of repo
  command = "./dendron-publish-site.sh"

[build.environment]
NETLIFY_NEXT_PLUGIN_SKIP = "true"

[[plugins]]
  # Installs the Lighthouse Build Plugin for all deploy contexts
  package = "@netlify/plugin-lighthouse"

[[plugins]]
  # Next.js plugin, to implement caching, etc.
  # https://github.com/netlify/netlify-plugin-nextjs
  package = "@netlify/plugin-nextjs"

Steps - Setup Netlify

Import GitHub project

Remote vaults and submodules

If the workspace requires notes from remote vaults, then they need to be added to the GitHub repository as git submodules. This will require creating deploy keys so that Netlify has the proper permissions to other repositories, if they are private or otherwise using ssh format (ex. git@github.com:owner/project.git).

The Netlify documentation covers this in Repository Permissions and Linking: Access other repositories at build. More information is available in Netlify Support Guide: How do I access private repositories in the build environment?

Upgrading

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

Congratulations, you just published your Dendron notes 🌱


Backlinks