Netlify

Summary

You can publish your notes using Dendron publishing and Netlify.

Prerequisites

• This assumes you have a Netlify account.
  • If not, you can create one.

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

• Dendron on Netlify Template: template.publish.netlify
  • The template, with every update, publishes to this example website

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.

Steps - Setup Dendron

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

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.

• Example netlify.toml from dendron/template.publish.netlify
  • Config file includes comments explaining the options used

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

• Login to Netlify
• Under Sites -> Import an existing project, click the Import from Git button
• Under Connect to git provider, click the GitHub button
• You will be prompted to install the Netlify app on GitHub
  • For more information on app permissions, refer to Netlify Docs: Authentication with the Netlify GitHub App

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

Related

• Netlify Docs: Get started with build configuration
• Netlify Docs: Custom domains
• Netlify Docs: Manage build dependencies - Node.js and JavaScript
• Netlify Docs: Get started with the Netlify API

Congratulations, you just published your Dendron notes 🌱

• Conclusion
• Cookbook
• Diagrams.net (Draw.io)
• Netlify