Converting content

The steps for moving a site's formatted text into BlockNote fields, in short. The converter in full has every option, what converts to what and the report.

Converting existing content

A site moving a body field from CKEditor to BlockNote converts its stored values with Drush, into a new BlockNote field beside the old one. The steps are in docs/converting.md section 9, and in short:

1. Add a BlockNote document field to each bundle, beside the text field, allowing the BlockNote format the documents are written in.
2. Rehearse with drush blocknote:convert node body field_body --dry-run, which writes nothing, and read documents.csv and elements.csv in the report directory it names. drush blocknote:convert-html shows what one value becomes.
3. In a maintenance window, run drush --uri=https://example.com blocknote:convert node body field_body, which converts each entity's current revisions, the published one and any draft, in place: no revision is added and nothing an editor sees changes but the new field. Running it again goes on where it stopped. In the same window, switch the form and the displays to the new field: a change an author makes to the old field afterwards is not in the new one.
4. Convert the older revisions with --revisions=older, at a quiet time, or decide not to: a revision left unconverted shows an empty field once reverted to.
5. Delete the old field.

An image or a link naming a file of the site becomes a block or a content link naming the file, and a link to content on the site a content link where the format permits them, so that they follow the file or the content wherever it moves. A site that has moved names its former addresses with --site-url=https://old.example.com and a former files path with --legacy-file-path=/files. An image whose file is in the public files directory but has no file record keeps its address unless --register-files asks for a file entity to be created for it.

With BlockNote Media installed, an embedded media item, an image whose file a media item holds, and a YouTube or Vimeo player whose video one holds become media blocks. --create-media --media-type=image --media-type=remote_video creates an item where none holds the file or the video, in the first of the types that holds it, when the document naming it is written, so a dry run creates nothing; an item created for a draft or an unpublished translation is unpublished, and an image or a player whose file or video only an unpublished item holds is left as it was. A conversion fetches nothing from the network, so a remote video type needs Queue thumbnail downloads ticked for it, and cron then fetches each new item's thumbnail and its title, which replaces the address the item is named by until then; core's Remote video type, which fetches each video's title and thumbnail as an item is saved, gets its items first from drush blocknote:create-videos node body field_body --media-type=remote_video, which saves them as an author would and can be run again after a failure. docs/converting.md section 3 says how.

Markup the converter cannot convert, such as an embedded map or a custom element, is kept in a block that the page leaves out and the editor shows as markup, as text: the document cannot be saved until an author has rebuilt what it held and removed it. The status report counts the documents still holding one, the revisions still holding text that is not converted, and the revisions whose old field an author changed after it was converted. --unconverted=drop leaves such markup out instead. The converter is experimental until it has run on a real site's content.