Skip to content

BlockNote

There is no stable release of this module yet. The only release is 1.0.x-dev, and the stored document format and the plugin and client contracts this document describes may still change before 1.0.0.

Development releases carry no security advisory coverage, so report everything about this module, security included, in the public issue queue.

Install with the explicit dev constraint, which needs no minimum-stability change in your own project:

composer require 'drupal/blocknote:1.0.x-dev'

Introduction

Integrates the BlockNote block editor with Drupal as a structured-document field type: an editing widget, a public formatter, text-format integration, and extension points for custom blocks, media and document workflows.

A BlockNote field stores a document as structured JSON, not as markup. The editor writes blocks, and Drupal renders those blocks into its own semantic HTML on the public page, so what is stored is the content and what a visitor sees is the module's markup.

A text format is the editor profile and the permission set. Which blocks an author may use, which inline styles and colours are permitted, and whether links are allowed are all settings of the BlockNote filter inside one text format, and who may write in that format is the format's own permission. This is the arrangement CKEditor 5 uses, applied to a field type this module owns.

Public pages load no editor JavaScript. The bundle is attached to forms that carry the widget and nowhere else, because the public output is rendered in PHP.

Requirements

  • Drupal 11.4 or newer.
  • PHP 8.3 or newer, which is what Drupal 11.4 requires.
  • Core's editor, field, file and filter modules, which the module declares as dependencies.

No JavaScript toolchain is needed to run the module. The editor bundle is committed to the repository, already built, and the module ships it as it stands. The toolchain in package.json is needed only to change the editor's TypeScript sources.

The editor supports the browsers in Drupal core's browser support matrix.

Tested with nodes, custom blocks and core's test entity types as the entities holding a document, with fields of cardinality 1 and of unlimited cardinality, in Default Admin, the administration theme that replaces Claro in Drupal 11.5. Default Admin is experimental in Drupal 11.4 and stable from 11.5. Claro, Gin and Olivero are each checked for the narrower things that Administration themes and Layout Builder describe.

Not included

These are outside 1.0:

  • Collaboration and comments. The module has no collaborative editing, no comment threads and no storage for either. A saved document is a snapshot of its blocks and keeps no comment anchors and no collaboration state, so a module that adds either stores its own. docs/workflows.md section 12 says what such a module can build on.
  • Entity usage. A file a document names, uploaded or linked, gets a file usage row, but a document naming a media item registers nothing, and there is no entity_usage integration; see docs/workflows.md section 13.
  • Workspaces. Nothing in the module is written for them, and no test runs a document inside a workspace.
  • BlockNote's XL packages, which hold its AI and multi-column features among others. Upstream licenses them under GPL-3.0 or commercially, and the editor bundle includes none of them.
  • Layout Builder, as its section describes.

Licence

The module is licensed GPL-2.0-or-later, like everything on drupal.org.

dist/blocknote.js and dist/blocknote.css are a compiled bundle of third-party code: the @blocknote/* packages under the Mozilla Public License 2.0, and their dependencies under MIT, ISC, Apache-2.0 and 0BSD. MPL-2.0 section 3.3 permits distributing those files inside a larger work under the GPL, and the covered files remain available under the MPL upstream and in this repository. Every package, its version, its licence and where its source is are listed in THIRD_PARTY_NOTICES.md, which is generated from the lockfile.

The Licensing Working Group has been asked to confirm that redistributing the MPL-2.0 packages in the bundle inside a GPL-2.0-or-later module is permitted, as #3578950, and whether the documented Remix Icon assets in js/icons/remix/ and modules/blocknote_media/js/icons/remix/ meet the policy on third-party assets, as #3578951. Neither has been answered. If you found MPL-2.0 or Apache-2.0 material in this repository and meant to report it, those are the places to read first.

The bundle is not the only third-party code here. js/src/mantine.css is a copy of a stylesheet from @blocknote/mantine, so the repository carries MPL-2.0 source form as well. That file stays under the MPL and says so at its head, and THIRD_PARTY_NOTICES.md records what was copied and where it came from.

Maintainers

Issues: https://git.drupalcode.org/project/blocknote/-/work_items