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 sincepackage-lock.json
oryarn.lock
can ensure all users/systems are using the samedendron-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
Pretty Links
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