protonsystems / paragraph-info

v2.1.1 2026-10-24 00:05 UTC

Requires

• php: ^8.3
• drupal/core: ^11
• drupal/paragraphs: ^1.23

GPL-2.0-or-later

Published on Packagist.org on 2026-10-24 05:06 UTC

README

This repository contains a reusable Drupal 11 module for exposing stable paragraph anchor IDs and, for permitted users, a toggleable paragraph info overlay.

Purpose

The module is intended to be reused across Drupal 11 projects by installing it as a Composer package and enabling it in the target site.

Requirements

• Drupal 11
• Paragraphs

Features

• Generates a canonical anchor for every rendered paragraph using: paragraph-{bundle}-{id}
• Exposes an opt-in paragraph info label for themes to render for users with the view paragraph info permission
• Adds separate toggles for paragraph information and unpublished paragraph review
• Persists each toggle state independently in browser localStorage
• Provides administrative settings for enabling the overlay, choosing its initial visibility, and controlling browser persistence
• Supports include/exclude filtering by paragraph type
• Automatically places labels before or after paragraphs, with theme-controlled placement for selected exceptional paragraph types
• Shows unpublished paragraphs directly in node previews and unpublished host content for users with Drupal's view unpublished paragraphs permission
• Can reveal unpublished paragraphs on published nodes through a separate frontend toggle, without exposing them to anonymous visitors
• Shows a page-level count warning and labels unpublished top-level paragraphs

Example anchor:

• #paragraph-text-42

Paragraph type filtering applies to information labels only. Anchor variables remain available for every rendered paragraph.

Structure

• paragraph_info.module contains the theme, page, and preprocess hooks.
• src/ contains the markup builder service.
• templates/ contains the information label, unpublished badge, and toggle Twig templates.
• css/ and js/ contain the frontend toggle behavior.

Installation

composer require protonsystems/paragraph-info

Then enable the module in Drupal:

drush en paragraph_info

Grant the View paragraph info permission to the desired roles, then rebuild caches.

To review unpublished paragraphs, keep the Paragraphs setting Show unpublished Paragraphs enabled and grant the desired editorial roles the View unpublished paragraphs permission. Do not enable the contributed unpublished_paragraphs module alongside this feature: its default-hidden CSS and separate toggle conflict with Paragraph Info's review workflow.

Custom paragraph templates should let Drupal's entity access decide whether a paragraph is rendered. If a project must retain an explicit publication-state condition in Twig, include the review-context variable exposed by this module:

{% if paragraph.published or paragraph_info_show_unpublished %}
  {# Paragraph markup. #}
{% endif %}

paragraph_info_show_unpublished is true only for an unpublished paragraph that the current user may review in a node preview, on an unpublished host, or through the unpublished paragraph toggle on the paragraph's published host node.

Configure the overlay at:

/admin/config/content/paragraph-info

Users need the Administer paragraph info permission to access this form.

Theme Integration

Use the paragraph_info_anchor_id variable in paragraph templates for the wrapper id.

Example:

<div id="{{ paragraph_info_anchor_id }}">
</div>

By default, the module automatically adds the information label before or after included paragraphs. For paragraph types configured to use theme-controlled placement, render paragraph_info_label at the required location in that paragraph template:

<div id="{{ paragraph_info_anchor_id }}">
  {{ paragraph_info_label }}
  {# Exceptional paragraph layout. #}
</div>

If a project already has theme-specific paragraph info labels or toggles, remove them to avoid duplicate UI.

CSS customization

Themes can override the module's design tokens without replacing its stylesheet. For example:

:root {
  --paragraph-info-label-background: #111827;
  --paragraph-info-label-color: #f9fafb;
  --paragraph-info-label-max-width: 80rem;
  --paragraph-info-unpublished-badge-background: #fff4ce;
  --paragraph-info-unpublished-badge-color: #5b3600;
  --paragraph-info-toggle-background: #7c3aed;
  --paragraph-info-toggle-bottom: 1.5rem;
  --paragraph-info-toggle-right: 1.5rem;
}

Available variables are defined with fallback values in css/paragraph-info.css.

Notes

Runtime options are exposed through the paragraph_info.settings service, and the module is designed to be consumed as a standard Drupal module package.