Netlify

Summary

You can publish your notes using Dendron publishing and Netlify.

Prerequisites

  • This assumes you have a Netlify account.

Dendron recommends installing dendron-cli in the local directory in order to avoid conflicts at the global level, and to keep Dendron versions isolated to each workspace. This is also beneficial for CI/CD systems, sharing repositories, and publishing your notes since package-lock.json or yarn.lock can ensure all users/systems are using the same dendron-cli.

# If dendron-cli is installed in the local directory via npm
# - Creates a package.json and package-lock.json
# - dendron-cli is only accessible in the directory this is ran in
# - dendron commands must be run like: `npx dendron <cmd>`
# - This is best practice for repos doing publishing, etc.
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 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 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 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 access your site.
  • Enter CTRL-C on the terminal to exit the preview
npx dendron publish dev

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