Migration

Summary

Upgrading Dendron configurations and dendron-cli for the latest and greates publishing updates.

Upgrade Dendron CLI

Please note that if you have an automated pipeline set up for publishing that uses dendron-cli, you need to manually upgrade dendron-cli so that is compatible with the current configuration version. Upgrading helps avoid errors due to configuration mismatch.

If there is a compatibility mismatch, running the CLI will display a message that the version does not meet the minimum compatible version. If you see this message, please upgrade dendron-cli to the latest version.

If upgrading with npm

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

If upgrading with npm (global)

# If dendron-cli is installed at a global level via npm
# - dendron-cli is accessible via any directory
# - Ensures dendron-cli can run without the `npx` prefix
# - dendron commands must be run like: `dendron <cmd>`
npm install -g @dendronhq/dendron-cli@latest

If upgrading with yarn

# If dendron-cli is installed via yarn
# - This means you have a package.json and yarn.lock
yarn upgrade @dendronhq/dendron-cli@latest

Upgrade dendron.yml configurations

General Configuration Upgrades

Dendron automatically checks your workspace for an outdated dendron.yml configuration when you open in VS Code / VSCodium. You will be prompted about migrating if a migration is necessary.

Migrations automatically create a backup configuration file in case you need to revert to an older CLI.

Manual upgrade of configurations via CLI

Instead of automatically through the VS Code / VSCodium, users can migrate the dendron.yml configuration to the latest version if the latest Dendron CLI is installed.

show_migrations

List available migration versions.

npx dendron dev show_migrations

run_migration

Migrate a config to the target version.

# Example
npx dendron dev run_migration --migrationVersion=0.83.0

Upgrading from Legacy 11ty

If you are coming from Dendron's legacy publishing (based on 11ty), you can look at the following guides for publishing.

If you were publishing using github pages without using github actions, follow the GitHub Pages guide.

If you were publishing using github pages with github actions, follow the GitHub Pages with GitHub Actions guide.

If you are publishing using an alternate platform, consult the GitHub Pages guide and adapt it for your specific platform.

If you run into any issues or have general questions, post in the publishing channel in discord for help.

Breaking Changes

Dendron Next.js publishing uses pretty urls which means pages will no longer have a .html suffix. If you are migrating an existing 11ty based Dendron site to Next.js, make sure to redirect .html pages to preserve existing links


Backlinks