Rewrite README.md with complete module documentation

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

README.md

@@ -1,8 +1,6 @@
-# Structural Pages - Design Document
+# Structural Pages
 
-## Overview
-
-The `structural_pages` module implements a hierarchical editorial structure and contextual navigation for institutional sites in Drupal 11. The module was designed for higher education institutions but is generic enough for other institutional contexts.
+Drupal 11 module that implements hierarchical editorial structure and contextual navigation for institutional sites. Designed for higher education institutions but generic enough for other institutional contexts.
 
 ## Problem
 
@@ -12,8 +10,135 @@ In Drupal, content is added in a flat manner (non-hierarchical), and menus are t
 
 The module implements two complementary structures:
 
-1. **Taxonomic Structure** (primary): Organization based on hierarchical taxonomy vocabulary
-2. **Parent-Child Structure** (subsidiary): Direct hierarchy between pages for specific cases, supporting multiple entity types as parents
+1. **Taxonomic Structure** (primary) — Organization based on the `site_sections` hierarchical taxonomy vocabulary, applied to the `section_page` content type. Governs breadcrumbs and URLs via Pathauto.
+2. **Parent-Child Structure** (subsidiary) — Direct hierarchy between pages via `field_parent_page` (Dynamic Entity Reference), applied to the `content_page` content type. Supports multiple parent entity types: nodes, taxonomy terms, users, and groups.
 
-See docs/DESIGN.md for details.
+## Requirements
 
+- Drupal 11
+- Core modules: `node`, `taxonomy`, `views`, `field`, `text`
+- Contrib modules:
+  - [Token](https://www.drupal.org/project/token)
+  - [Pathauto](https://www.drupal.org/project/pathauto)
+  - [Dynamic Entity Reference](https://www.drupal.org/project/dynamic_entity_reference)
+- Optional:
+  - `content_translation` — for multilingual taxonomy term names
+  - [Group](https://www.drupal.org/project/group) — for group entity support (via `structural_pages_group` submodule)
+
+## Installation
+
+```bash
+drush en structural_pages -y
+drush cr
+```
+
+The module automatically creates:
+- Taxonomy vocabulary `site_sections` with default hierarchical terms
+- Content types `section_page` and `content_page` with configured fields
+- Pathauto patterns for both content types and taxonomy terms
+- A `child_pages` View (block display)
+- Content translations for term names (if `content_translation` is enabled)
+
+### Group support
+
+```bash
+drush en structural_pages_group -y
+```
+
+Requires the Group module. Adds group entities as a parent type for content pages.
+
+## Configuration
+
+**Settings form**: `/admin/config/local-modules/structural-pages`
+
+Allows administrators to select which entity types and bundles can be used as parents for content pages. Changes automatically update the `field_parent_page` field configuration.
+
+## Content Types
+
+### section_page
+
+Pages organized by site section. Each page belongs to a `site_sections` taxonomy term.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `field_site_section` | Entity reference (taxonomy) | Yes | Site section |
+| `body` | Formatted text | No | Page content |
+
+### content_page
+
+Pages with hierarchical parent-child structure. The parent can be a node, taxonomy term, user, or group.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `field_parent_page` | Dynamic entity reference | No | Parent entity |
+| `field_site_section` | Entity reference (taxonomy) | Conditional | Site section (inherited or manual) |
+| `body` | Formatted text | No | Page content |
+
+**Site section inheritance rules:**
+- Parent is a `taxonomy_term` → uses the term as site section
+- Parent is a `node` → inherits `field_site_section` from the parent node
+- Parent is a `user` or `group` → clears `field_site_section` (context is the entity itself)
+- No parent (root page) → must be filled manually
+
+## Features
+
+### Automatic breadcrumbs
+
+Custom breadcrumb builder for `section_page` and `content_page` that traverses the parent chain:
+
+- **Taxonomy context**: Home > Term Hierarchy > Parent Nodes > Current Page
+- **User context**: Home > User Name > Parent Nodes > Current Page
+- **Group context**: Home > Group Name > Parent Nodes > Current Page
+
+### Pathauto tokens
+
+| Token | Description | Example |
+|-------|-------------|---------|
+| `[node:site-section-path]` | Hierarchical path from taxonomy | `undergraduate/courses` |
+| `[term:hierarchy-path]` | Term path including ancestors | `institutional/news` |
+
+Suggested URL pattern: `[node:site-section-path]/[node:title]` → `/undergraduate/courses/software-engineering`
+
+### Structural Pages Menu block
+
+Dynamic menu block that renders hierarchical navigation based on content structure.
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| Maximum depth | 3 | Number of levels to display (1-10) |
+| Show ancestor title | Yes | Display ancestor entity title as header |
+| Expand active trail | Yes | Highlight the path to current page |
+
+### Child Pages View
+
+Block display that lists child pages of the current `content_page`, filtered by `field_parent_page`.
+
+## Extensibility
+
+The module uses an attribute-based plugin system (`ParentEntityHandler`) to support different parent entity types. Built-in handlers:
+
+| Handler | Entity Type | Clears Site Section | Bundle Restrictions |
+|---------|-------------|---------------------|---------------------|
+| TaxonomyTermHandler | taxonomy_term | No | site_sections |
+| NodeHandler | node | No | content_page, section_page |
+| UserHandler | user | Yes | - |
+| GroupHandler* | group | Yes | - |
+
+*Provided by the `structural_pages_group` submodule.
+
+To add support for a new entity type, create a plugin in `src/Plugin/ParentEntityHandler/`:
+
+```php
+#[ParentEntityHandler(
+  id: 'my_entity',
+  label: new TranslatableMarkup('My Entities'),
+  entity_type_id: 'my_entity',
+  clears_site_section: FALSE,
+  sort_field: 'title',
+)]
+class MyEntityHandler extends ParentEntityHandlerBase {
+  // Override methods as needed.
+}
+```
+
+See `docs/DESIGN.md` for full architecture details and `docs/PLUGIN_SYSTEM_PLAN.md` for the plugin system design.