Issue #3619188: Make the setup instructions complete

Marcelo Vanirequested to merge
3619188-readme-instructions into 8.x-1.x

Rewrites the setup instructions after working through them as a first-time user.

The gap that matters

Permissions were not mentioned at all. Entity Browser generates a permission per browser, and without Access Paragraph items pages (access paragraph_items entity browser pages) the toolbar button opens the dialog on an Access denied page instead of the Paragraph type selector.

Nothing led the reader to it, because the permission is named after the entity browser rather than after this module. This is not hypothetical — it is the first thing the FunctionalJavascript tests in #3040507 failed on.

The rest

The allowed HTML step pointed at a config file. It linked to line 16 of the example module's filter.format YAML and left the reader to work it out. Getting this wrong silently strips embedded paragraphs when the text is filtered, so the <drupal-entity> tag and its attributes are now written out, along with the narrower variant the example module uses.

There was no description of the editing experience. The README covered configuration and stopped, so there was no way to tell whether the configuration had worked. A How editors use it section now walks the flow from toolbar button through to the saved, rendered paragraph.

A known console error was undocumented. Selecting an embedded entity logs Cannot read properties of undefined (reading 'pencil') from Entity Embed. Embedding still works, but anyone who opens the console will reasonably conclude the module is broken. This is upstream — entity_embed #3575503, which has a merge request under review — and tracked here as #3619182.

One correction. The embed button's bundles field is labelled Paragraph type, not "Allowed Entity Bundles": Entity Embed uses the entity type's own bundle label.

Structure

Requirements
Installation
  1. Install the module
  2. Choose which Paragraph types editors may embed
  3. Add the button to a text format
  4. Allow the embed markup
  5. Grant the permissions        <- was missing
How editors use it               <- new
Trying it out
Troubleshooting                  <- new
Known issues
Drupal 12
Development

Verified, not assumed

Checked against a running Drupal 11.4.5 site with the module installed: the embed button and entity browser are both created on install, all four admin paths in the instructions resolve, and the permission machine name and its UI label are as written. The editor walkthrough is the flow I stepped through by hand.

The project page repeats the README, so it is worth mirroring these changes there too.

Merge request reports