MIGRATE FROM
NETLIFY CMS
Netlify CMS is now Decap CMS, and neither is actively developed. Your markdown files stay exactly where they are. Only the editing interface changes.
This guide walks through every step: from auditing your config.yml to deleting the /admin/ folder for the last time. Most teams finish in under 30 minutes.
WHY NETLIFY CMS IS BEING ABANDONED
Netlify stopped investing in Netlify CMS sometime around 2022. The community eventually forked the project and renamed it Decap CMS, but the pace of development is slow. Releases are infrequent, the underlying CKEditor is outdated relative to modern editors, and the roadmap is thin.
The bigger pain point for many teams is Git Gateway, the auth mechanism that routes your GitHub writes through a Netlify serverless function. Git Gateway requires you to have a Netlify site (even if you host the actual site elsewhere) and adds a round-trip to every save. When Netlify changes something on its end, editors break with confusing error messages.
The widget model also has age showing on it. Defining custom widgets in YAML is fine for a simple blog, but it does not scale to teams that need conditional fields, repeated groups, or schema validation. There has been no meaningful investment in this area.
To be direct: Decap CMS still works for simple, low-traffic sites where nobody needs to extend the schema. If that describes your project, there is no urgency. But if you want active development, a modern editor, and auth that does not depend on a Netlify account, migrating is worth the 30 minutes it takes.
WHAT STAYS THE SAME
The most important thing to know before you start: md0 does not touch your content. It reads the same .md and .mdx files Netlify CMS was writing. Nothing moves, nothing converts, nothing breaks.
WHAT CHANGES
The changes are entirely about the editing infrastructure, not the content. Your readers and your build pipeline will not notice anything different.
NO /ADMIN/ FOLDER
The /admin/ folder and its config.yml go away. md0 is fully hosted. Nothing lives in your repository to configure the CMS.
NO PROXY SERVER
netlify-cms-proxy-server was a local dev workaround. With md0, the GitHub API is called directly. No proxy needed in development or production.
DIRECT GITHUB OAUTH
Git Gateway is replaced by GitHub OAuth directly through md0. No Netlify account needed for auth. Login is faster and more reliable.
VISUAL COLLECTION BUILDER
config.yml is replaced by a point-and-click collection builder in the md0 UI. You define fields, paths, and schema without writing YAML.
MIGRATION STEPS
Work through these steps in order. Steps 1 and 2 are prep work you do before touching md0. Steps 3 through 6 are the actual migration. Steps 7 and 8 are optional cleanup.
Open config.yml and take notes
Find public/admin/config.yml (or static/admin/config.yml). For each collection, write down: the folder path, the create flag, and every field name and widget type. You will recreate these in md0.
Identify all collections and their field types
List every item under collections:. Note which fields are required, which have defaults, and whether any use the list or object widget. These need the most attention when mapping to md0 field types.
Remove Git Gateway and Netlify Identity from netlify.toml
If your netlify.toml has a [build] or [[plugins]] block referencing netlify-identity-widget or git-gateway, remove those lines. They are not needed with md0 and can interfere if left in.
Sign up for md0 CMS and connect your GitHub repository
Go to cms.md0.io and log in with GitHub. Grant access to the repository. md0 reads the repo structure immediately with no additional configuration required at this stage.
Create collections in md0 to match your Netlify CMS collections
For each collection you noted in step 1, create a matching collection in md0. Set the folder path to the same value (e.g. content/blog), add fields matching your widget types using the field type mapping below.
Test editing a piece of content
Open a content item in the md0 editor and make a small change. Save it. Check your GitHub repository and you should see a new commit from md0. Your build pipeline picks this up as normal.
Remove /admin/ and /static/admin/ from your repository
Once you are confident md0 is working, delete the admin folder and commit that change. This removes the old config.yml, index.html, and any identity widget scripts.
Update CI/CD references that check for config.yml
Search your GitHub Actions workflows and any deploy scripts for references to config.yml, netlify-cms, or netlifycms. Update or remove those checks so they do not fail on the now-absent file.
FIELD TYPE MAPPING
Every Netlify CMS widget type has a direct equivalent in md0. The table below covers all standard widgets. If you used a community widget, map it to the closest primitive type and add a note in the field description.
stringtextmarkdowndatetimeimagebooleanselectlistobjectThe relation and map widgets do not have a direct equivalent yet. Use a select field with a static option list as a short-term replacement.
COMMON GOTCHAS
These are the issues most teams run into when migrating. All of them are quick fixes once you know what to look for.
Proxy server in package.json scripts
Many Netlify CMS projects add npx netlify-cms-proxy-server to their dev start script so local edits bypass Git Gateway. With md0, the GitHub API is called directly from the hosted app. There is no proxy and no local server to run. Remove any netlify-cms-proxy-server references from package.json scripts and from your npm run dev README instructions.
Editorial workflow (draft PRs)
Netlify CMS has an optional publish_mode: editorial_workflow setting that opens a GitHub pull request for each draft, letting team members review before publishing. md0 writes directly to your configured branch instead of opening PRs. If your team relied on this review flow, plan a replacement: the simplest option is a status frontmatter field (draft, review, published) that your static site generator can use to filter which content gets rendered.
media_folder path
Netlify CMS's media_folder config key sets where uploaded images land in your repository. md0 has a matching media path setting in the collection configuration. Set it to the same path (e.g. public/uploads or static/images) and existing image references in your markdown files will continue to resolve correctly.
Netlify Identity widget script
Some Netlify CMS setups add a <script src="https://identity.netlify.com/v1/netlify-identity-widget.js"> tag to the site's main HTML (not just the admin panel). If you added this to your public layout, remove it. It is a Netlify-specific script that serves no purpose once you have migrated.
Related
Still comparing? md0 CMS vs Netlify CMS | All migration guides
MIGRATE TODAY
Your markdown files stay unchanged. Only the editing interface changes.
Connect your GitHub repository at cms.md0.io and start editing in minutes.
START NOW