# Mangrove page building guide for Drupal Gutenberg > How to build landing pages on UNDRR websites (undrr.org, preventionweb.net, mcr2030.undrr.org and the microsites) with the Drupal Gutenberg block editor and Mangrove components: page shapes, section structure, layout patterns and component choice, then the UNDRR block reference with serialization rules, rendering constraints and the current markup for every block. Markup can be pasted into the editor through the Code editor. For copy, follow the editorial manual; for search widget configuration, fetch llms-search-widget.txt. # Building landing pages > **About this guidance:** this page brings together guidance maintained elsewhere and is provided for reference and ease of access. It is not the authoritative source. Where it differs from a source, or doesn't cover a point, follow the source: the block definitions in the Drupal `undrr_gutenberg_blocks` module as deployed (for block behaviour and markup), the [Editorial manual](https://mangrove.undrr.org/?path=/docs/contributing-editorial-manual--docs) and the sources it cites (for writing and style) and the [UNDRR Web Style Guide](https://unitednations.sharepoint.com/sites/UNDRR-DRR-COMMS/SitePages/Web-Style-Guide.aspx) (UNDRR staff only) (for UNDRR web style). Guidance for editors building landing pages on UNDRR websites: which page shape to start from, how to structure sections and which Mangrove component suits each job. The structure and editorial advice comes first in each section; the Drupal Gutenberg markup that produces it follows. ## Quick start for editors > **First version:** a short outline for building a page in the visual editor, without writing code. A fuller editor guide will follow; the rest of this page has the detail. 1. **Pick a page shape.** Decide what the page is for, then find its shape in [Choose a page shape](#choose-a-page-shape). 2. **Insert a starting pattern.** Open the block inserter, switch to patterns and choose the **UNDRR pages** category. Insert the pattern closest to your page shape: a reading page, an initiative overview, a publication collection or a frequently asked questions section. 3. **Replace the placeholders.** Rewrite every heading and paragraph, and check every link destination. Select each image, hero and card and choose a real image from the media library, with alt text and a photo credit. Follow the [Editorial manual](https://mangrove.undrr.org/llms-editorial-manual.txt) for the words. 4. **Add a search widget if the page needs one.** Insert the **UNDRR Search Widget** block from the **UNDRR** category of the inserter and set it up in the block sidebar. [Search widget editor configuration](https://mangrove.undrr.org/llms-search-widget.txt) explains each setting and has ready-made recipes. 5. **Preview.** Check the page before publishing, including at a narrow window width, and fix any block that shows a validation warning. 6. **Publish** the page the way your website's editorial workflow requires. Developers, and AI tools that write block markup, should start from [Drupal Gutenberg integration](#drupal-gutenberg-integration), which has the current markup for every block. The [Landing page patterns](https://mangrove.undrr.org/?path=/docs/patterns-landing-pages--docs) page shows the three common page shapes rendered side by side. [Drupal Gutenberg integration](#drupal-gutenberg-integration) covers how each UNDRR block serializes and has the current markup for every block; this guide links to it rather than repeating it. > **Tip:** An AI tool can read this guide and the integration guide as one plain-text file: . [Using this guide with an AI tool](#using-this-guide-with-an-ai-tool) has a prompt to start from. ## Writing for landing pages This guide covers structure, not prose. For the words on the page: - [Editorial manual](https://mangrove.undrr.org/llms-editorial-manual.txt): capitalization, punctuation, numbers and dates, abbreviations, spelling, UNDRR terminology and inclusive language. It is the single source for these rules; the other guides link to it rather than restating it. - [Writing guidelines](https://mangrove.undrr.org/?path=/docs/contributing-writing-guidelines--docs): plain language, front-loading and descriptive link text. Its rules on second person are written for interface copy; body copy on a landing page follows the editorial manual. - UNDRR editorial guides for news, events, publications and blogs, being published at . Points specific to landing pages: - Write for the people who use UNDRR websites: Member States, disaster risk reduction practitioners, researchers and policymakers. - Give every H2 section a short introduction of one or two sentences that says what the reader will find below. Keep it factual and action-oriented, and reference the Sendai Framework where it fits naturally. - Use "disaster risk reduction" rather than "disaster management" or "disaster prevention", and spell it out before abbreviating it to DRR. Use "hazard" for the natural phenomenon and "disaster" for its impact on people. - Headings are in sentence case. ## Choose a page shape Decide what the page is for before choosing blocks. Most UNDRR landing pages are one of these: | The page… | Shape | Start from | | --- | --- | --- | | Introduces a subject and points several ways into it | Topic or initiative | A split hero, an on-this-page bar, then routes and recent material | | Is one long document that people cite sections of | Report or publication | A coloured header with a contents sidebar, or a hero with an on-this-page bar; see [Publication landing page](#publication-landing-page) | | Exists to reach many items | Collection index | A plain H1, a contents block and rows of book cards; see [Card grid rows](#card-grid-rows) | | Presents several charts about one place or theme | Data page | See [Data chart page](#data-chart-page) | | Is returned to repeatedly, with movement between sections | Content hub | See [Content hub](https://mangrove.undrr.org/?path=/docs/patterns-content-hub--docs) | The inserter's **UNDRR pages** pattern category has starting points for a reading page, an initiative overview, a publication collection and a frequently asked questions section. ## Page structure ### Page title Every page has exactly one H1. Either the hero supplies it (`headingLevel` `h1`) or a level 1 heading block does. Do not use the Drupal page title block (`drupalblock/page-title-block`) in the page body. ```html

Page title

``` For a large display title on a publication or campaign page, set the font size to **Huge**, which saves `has-huge-font-size mg-u-font-size-800`. ### Choosing a hero The hero block has two layouts: - **Split** (preferred for new pages): text in one column and an image, video or custom HTML in the other, on a solid theme colour. Contrast is predictable because the text never sits over a photograph. - **Background** (legacy): text over a full-bleed image. Existing background heroes do not need migrating, but new pages should use split. A newly inserted hero block starts on the background layout, so switch **Layout** to split in the block sidebar. To draft a split hero before the image is in the media library, leave the image out: the hero saves no media column until an image is chosen, and the rest of the block still works. [Drupal Gutenberg integration: Hero](#hero) shows what to leave out of hand-written markup. Split ratios describe the **content** column, which is the easiest thing to get backwards: | Ratio | Content column | Use for | | --- | --- | --- | | 2/3 (default) | Two thirds | Text-led heroes: a long lede, several buttons, a supporting image | | 1/2 | Half | Equal weight for a short lede and a strong image | | 1/3 | One third | Video heroes, and any hero where the media is the message | Use 1/3 for video: a video in a one-third column is too small to watch. Use custom HTML media for a statistic callout, a small chart or a captioned figure. A hero has no slot for a contents list. Pair a hero with the [on-this-page bar](#in-page-navigation) directly below it, or use the [page header with a contents sidebar](#page-header-with-a-contents-sidebar) instead of a hero. A page with both reads as two headers. Markup and attributes: [Drupal Gutenberg integration: Hero](#hero). ### In-page navigation Long pages need a way to jump between sections. There are two blocks for this, and a page uses one of them: - **On this page navigation** (`undrr/undrr-on-this-page-nav-block`): a sticky horizontal bar built from the H2 headings. Use it on narrative and campaign pages, directly after the hero. To keep a download in view as the reader scrolls, turn on its call-to-action link. - **Table of contents** (`undrr/undrr-table-of-contents-block`): a contents list, usually in a sidebar of the page header. Use it on index and reference pages. Both read the page's headings, so the headings are the navigation: keep H2 text short and specific. To leave a heading out, add a class to it: `mg-on-this-page-nav--exclude` for the on-this-page bar, `mg-table-of-contents--exclude` for the contents list. Markup: [Table of contents](#table-of-contents) and [On this page navigation](#on-this-page-navigation). ### Page header with a contents sidebar The reference-page alternative to a hero: a full-width coloured band with the title and lede on the left and the contents block on the right. The colour attributes go on the outer columns block, and the contents block sits directly in the right column. ```html

Page title

[lede paragraphs and a left-aligned outline download button]
[table of contents block]
``` When the introduction runs on after the header, continue it in a plain 66.66/33.33 columns block so the text stays aligned under the header. ### Section introductions Each H2 section opens with its heading and a one- or two-sentence introduction, then its content. On campaign and long narrative pages, section H2s can be set to the **Huge** font size for a stronger break between sections; keep default sizing on index and reference pages. ### Section backgrounds A full-width tinted band marks a change of job, such as a hand-off or a call to action at the end of a narrative run. On index pages, alternating white and light grey sections give a long page some rhythm. Used on every ordinary section, tinted bands just stripe the page. Wrap the section in a columns block with one column. Do not use a group block as the wrapper; it breaks in Drupal Gutenberg. ```html
[H2, introduction and the section content]
``` To hold the section content to the default content width inside the band, put a constrained group inside the column. This is the one place a group block works: ```html
[H2, introduction and the section content]
``` For a band that also needs a centred reading column, put the percentage columns (below) directly in the band's columns block rather than nesting a second one. Background colours belong on a container, not on a column in a row. A coloured column has no padding, so the text runs to its edges. For a call-out beside body text, put a [Highlight box](#highlight-box) in a plain column instead. ### Reading column widths Long lines are hard to read. On narrative pages (annual reports, flagship publications, concept notes), centre body text in a narrower column and let full-width elements such as the hero, the on-this-page bar and stats cards break out of it. The side columns collapse on mobile. | Split | Use for | | --- | --- | | 15/70/15 | Wide featured text, a hero-style lede, full-width call-to-action bars and download buttons | | 20/60/20 | Body prose: roughly four or more consecutive paragraphs, and show-more targets | ```html
[paragraphs]
``` Do not use reading columns on index and reference pages, where full-width card rows use the space better. ### Spacing Headings carry the rhythm, not spacers. A spacer between every H2 is usually the wrong tool; default block spacing plus clear section headings reads better, with a spacer kept for a genuine break. Where spacers are used, these values keep pages consistent: | Where | Spacer | | --- | --- | | Between H2 sections on index and reference pages | 60px | | Between H2 sections on campaign and narrative pages | 45px | | Above the contents block, and below it | 32px, 40px | | Between chart rows in a data page section | 40px | | Top and bottom inside a tinted band | 48px | | Between two tightly coupled blocks | 8px | Card rows within a section need no spacer; default block spacing handles them. ### Composition defaults Observations from pages that have been through editorial review, offered as defaults rather than rules: - **Fill the short column or do not split.** A 66.66/33.33 split with an empty right column looks like a mistake once it repeats down a page. Put the pull quote, supporting image or diagram there. - **Stats cards want full width.** In a one-third column their figures stack into a narrow strip. Place them between sections, not inside a split. - **Buttons align left**, on the same axis as the text they follow. Centred buttons float free of the reading column. - **A large first paragraph works as a lede.** The **Large** font size on a section's opening paragraph gives readers a way in without another heading level. ## Page archetypes ### Card grid rows For collection index pages, which exist to reach many items: - Put a full-width H3 above each row of cards, not inside a column. - Below the H3, add a paragraph linking to the subsection's own landing page. Name the destination in the link text ("All early warning resources"), not a generic "View landing page", which reads the same for every row to a screen reader user scanning links. When the subsection covers two related topics, add both links separated by a line break. - Lay book cards out in five-column rows, and pad a short row with empty columns so the covers keep their size. - When two neighbouring subsections have only one or two cards each, merge them under one H3. - Turn items that do not suit a card (training modules, other landing pages) into text links. - Put editorial labels such as "(Suggested)" in the title text rather than the card's label. ```html

Subsection name

All early warning resources

[book card]
[book card]
[book card]
``` Book card markup is in [Drupal Gutenberg integration: Card](#card). ### Publication landing page For annual reports and other PDF-led publications, the web page is a guided tour that sends readers to the full document, not a copy of it: 1. A hero with the cover image or a video. 2. An on-this-page bar with a download call to action. 3. The foreword or introduction in a 15/70/15 reading column. 4. Key figures in full-width stats cards. 5. Thematic H2 sections, each with a story preview cut to two or three paragraphs and a "Read more in the full report (PDF)" link. 6. Quote highlights for official quotes from named people. 7. Cross-cutting themes as vertical cards linking to the thematic pages, rather than repeating text that is already in the PDF. 8. A download section with book cards for the PDF and any annexes. 9. A "More on UNDRR" section with vertical cards linking to related pages. Alternate white and grey section backgrounds down the page. Global Assessment Report 2025 and the UNDRR Annual Reports 2024 and 2025 follow this shape. ```html

The first two or three paragraphs of the story from the report.

Read more in the full report (PDF)

``` ### Data chart page For pages built around several charts, such as country resilience profiles or thematic dashboards, with three to five thematic sections. Keep prose brief: one framing sentence per section and one key finding per chart. 1. A full-width blue header: a back link, the H1, a row of metadata in four columns, a separator and a one- or two-sentence lead paragraph, in white text. 2. An on-this-page bar built from the H2s. 3. Thematic sections, alternating white and grey. Each opens with a short section label, an H2 with an anchor and a framing paragraph, followed by one row per chart. Each chart row is a columns block split 33.33/66.66: an H3 stating the key message, one or two sentences of supporting data and an outline button on the left; the chart and its caption on the right. ```html

[Key finding, stated as a message]

One or two sentences supporting the key message with specific data.

[Metric, units and scope]. Source: [organization] ([year])

``` Chart titles and captions follow a convention. The text in square brackets is a placeholder: write the finding and source from the data the chart shows. | Element | Content | Form | | --- | --- | --- | | H3 in the left column | The key takeaway, stated as a message | "[What the data shows, in one sentence]" | | `iframe` `title` | The same text as the H3; it is the chart's accessible name | The H3 text | | Caption paragraph | Neutral: metric, units, scope and source, with the source line following the [editorial manual's template](https://mangrove.undrr.org/llms-editorial-manual.txt#undrr-specific-terminology) | "[Metric] ([units]), [scope]. _Source_: [organization] ([year])" | | Title inside the chart | Can be hidden in the chart tool's publish settings | | Datawrapper's own embed code adds a script that resizes the iframe; include it in the same `wp:html` block. ### Logo wall For partner and consortium logos, use icon cards with `imageScale` `full` and `centered` on, six to a row, inside a 10/80/10 centring wrapper. - For an organization with no usable logo, use a text-only icon card. - For a logo that only exists in white, give that one column `"backgroundColor":"undrr-blue","textColor":"white"`. - A first version can hotlink logos from the organizations' own websites by setting the image URL and leaving out `mediaID`; upload them to the media library before the page is final. Icon card markup is in [Drupal Gutenberg integration: Card](#card). ## Choosing components ### Cards | Content | Card | | --- | --- | | Topics, programmes or pages, each with a picture and a short description | Vertical card (`vc`) | | The same, where a row of vertical cards would be too tall | Horizontal card (`hc`) | | Publications and documents with a cover | Book card (`book`), or horizontal book card (`hc_book`) in a list | | Partner logos and short route links | Icon card (`icon`) | - Always give vertical and horizontal cards an image. Without one they lose their border, background and padding and render as bare text. - Keep summaries to two or three sentences. Long summaries make rows ragged, because each card grows to its own content. - Cover images are decorative when the title is beside them: set `mediaAlt` to an empty string. Photographs in content cards need descriptive alt text. - Publication cover scans (the generated document thumbnails in the media library) look wrong in a vertical card; use a photograph. ### Figures and statistics Use the [stats card](#stats-card) for headline figures, at full width. When there are more figures than fit one row, put several single-stat cards, each without a title, inside a [scroll container](#scroll-container) rather than stacking rows. Write figures the way the [editorial manual](https://mangrove.undrr.org/llms-editorial-manual.txt#numbers-and-dates) sets out. ### Quotes Use the [Quote highlight](#quote-highlight) block for a quote with a named speaker, their title and optionally a portrait. For a pull quote with no attribution beside body text, a blockquote in the right-hand column of a 60/40 split is lighter: ```html
[H2 and body paragraphs]
Pull quote text.
``` ### Show more The show more button collapses a long block, such as a list of resources, behind a toggle. It needs two things: a unique class on the block to collapse, and a layout that centres the button. 1. Give the content's columns block a class such as `show-more-target-k7q2xa`, with a random six- to eight-character suffix so that two show more blocks on one page cannot collide. 2. Put the button in its own columns row directly below, in the middle column of a 40/20/40 split. 3. Add a page-level style to centre the button. ```html
[content to collapse]
Show more
``` ### Frequently asked questions and long reference content There are two tools for content that readers expand one item at a time: - **A short set of questions** (up to about ten): use the **Frequently asked questions** pattern from the **UNDRR pages** category. It inserts core Details blocks with the Mangrove presentation switched on, one per question. Details are native HTML disclosures, so they need no script and the browser's find-in-page search reaches the answers. - **Long reference content**, such as a long question list or the Sendai Framework targets and indicators: use stacked tabs with **Show filter input** and **Single open (accordion)** turned on, so readers can type a word and go straight to the matching section. Horizontal tabs are the wrong tool here; they truncate their labels and make readers click through each tab. Write section labels with the words a reader would search for. When a stacked tab set sits inside an H2 section and the tab labels are the only headings needed, turn on **Hide heading** for each section. Otherwise each open panel repeats its label as a visible H2 below the tab, which duplicates the heading. Markup: [Drupal Gutenberg integration: Tabs](#tabs). ### Images and video - Use images from the media library, with alt text that describes what the image shows. Every photograph needs a credit. - Put images inside a reading column rather than full width, unless the image is the point of the section. - For video, use the embed block with the ordinary YouTube or Vimeo URL, and put the caption in a small paragraph after it. Hero video is different: it needs the `/embed/` URL. Markup: [Drupal Gutenberg integration: Core blocks](#core-blocks-used-alongside-the-undrr-blocks). ## Starter page A minimal index page: title, contents, one white section of book cards and one grey section. Paste it through the Code editor, then replace the placeholder text, links and images; `[cover image URL]` stands for the URL of an image chosen from the media library. Elsewhere in this guide, text in square brackets is a placeholder. On a line of its own, such as `[book card]`, it marks where other blocks go and is not valid block markup, so replace it with real blocks before pasting. Inside a block, such as `[Key finding, stated as a message]`, it is a value to replace with real content. ```html

Landing page title

First section

One or two sentences on what readers will find in this section.

Second section

One or two sentences on what readers will find in this section.

Replace this paragraph with a row of cards, as in the first section.

``` ## Found a problem? If something in this guide is wrong or out of date, open an issue in the [Mangrove issue queue](https://github.com/PreventionWeb/undrr-mangrove/issues) (a GitHub account is needed). ## Related documentation - [Drupal Gutenberg integration](#drupal-gutenberg-integration): block reference, serialization rules and rendering constraints - [Search widget editor configuration](https://mangrove.undrr.org/llms-search-widget.txt): adding a search or "latest content" panel to a page - [Landing page patterns](https://mangrove.undrr.org/?path=/docs/patterns-landing-pages--docs) and [Content hub](https://mangrove.undrr.org/?path=/docs/patterns-content-hub--docs): rendered examples of these shapes - [Component gallery](https://mangrove.undrr.org/?path=/docs/brand-component-gallery--docs): every component, grouped by what it is for # Drupal Gutenberg integration > **About this guidance:** this page brings together guidance maintained elsewhere and is provided for reference and ease of access. It is not the authoritative source. Where it differs from a source, or doesn't cover a point, follow the source: the block definitions and `save()` output in the Drupal `undrr_gutenberg_blocks` module as deployed (for blocks, attributes and markup), the [Editorial manual](https://mangrove.undrr.org/?path=/docs/contributing-editorial-manual--docs) and the sources it cites (for writing and style) and the [UNDRR Web Style Guide](https://unitednations.sharepoint.com/sites/UNDRR-DRR-COMMS/SitePages/Web-Style-Guide.aspx) (UNDRR staff only) (for UNDRR web style). UNDRR websites (undrr.org, preventionweb.net, mcr2030.undrr.org and the microsites) run on a shared Drupal platform, and editors build landing pages there with the Gutenberg block editor. Most of what an editor places on a page is a Mangrove component wrapped in a Gutenberg block. This page is the thin layer between the two: which block renders which component, how the blocks serialize, what the deployed build can and cannot render, and the current markup for each block. It has two companions: - [Building landing pages](#building-landing-pages): the editorial and structural guidance, meaning which page shapes to use and how to compose them. Start there if you are planning a page. - [Search widget editor configuration](https://mangrove.undrr.org/llms-search-widget.txt): filters, facets and search syntax for the UNDRR search widget block. ## Using this guide with an AI tool The Storybook site is a single-page app, so an AI tool that fetches a Storybook URL gets an empty shell. Every build publishes this guide and [Building landing pages](#building-landing-pages) as one plain-text file instead: . The search widget reference has its own file: . Use this prompt in any AI tool that can fetch URLs: > Using the UNDRR page building guide at https://mangrove.undrr.org/llms-page-building.txt, draft a Drupal Gutenberg landing page about disaster preparedness with a split hero, an on-this-page navigation bar and three sections of book cards. Replace everything after "draft" with your page brief. Add to the prompt when the tool is also writing the copy, and when the page needs a search widget. If you use Claude Code or Cursor with access to the block module source, the [drupal-gutenberg-llm-skills](https://github.com/khawkins98/drupal-gutenberg-llm-skills) plugin gives better results because it validates against the full block definitions. Review AI output in the editor before publishing. A block the editor cannot validate shows an "Attempt block recovery" prompt; recovering it rewrites the markup to what the block would save, which usually drops attributes. The search widget is an exception: all its settings are in the block comment, so recovery rebuilds its markup from them and loses nothing. ## Platform context The platform uses the [Drupal Gutenberg module](https://www.drupal.org/project/gutenberg), a port of the WordPress block editor to Drupal. Block comments keep the WordPress `wp:` prefix, but a few things differ from WordPress: - Landing pages use the `landing_page_gutenberg` content type. - Blocks are registered in JavaScript and `*.gutenberg.yml`; there is no `block.json`. - Libraries load through Drupal's `*.libraries.yml`, not `wp_enqueue_script()`. - Translations use `Drupal.t()`, wrapped as `__()` in block code. - `wp:group` does not work as a standalone section wrapper. Use `wp:columns` with a single `wp:column` child instead (see [Serialization rules](#serialization-rules)). The UNDRR blocks live in the `undrr_gutenberg_blocks` Drupal module, in the platform codebase. Each block's `save()` function writes Mangrove markup (the `mg-` classes and `data-mg-*` attributes documented on each component page), and the Mangrove CSS and scripts that the theme loads style and hydrate it on the published page. ## Pasting markup into the editor 1. Open the page in the block editor. 2. Open the three-dot menu at the top right and choose **Code editor**. 3. Paste the markup where it belongs, then choose **Exit code editor**. 4. Check every block in the visual editor. A block with a validation warning has markup that does not match what the block saves; fix the markup or rebuild that block in the visual editor. The body field's text format must be **Gutenberg**. It is the only format that parses block comments, renders dynamic blocks and resolves embeds. Markup saved under any other format, Full HTML included, is stored without complaint and then rendered as plain HTML: embeds print their URL as text, dynamic blocks such as the media entity block render nothing, and every block comment appears in the page source. Static blocks still look right, so a page can seem mostly fine while every dynamic block is broken. ` ``` A notes block like this at the top of a page is a useful place for editors to leave instructions for each other. ### Headings Level 2 is the default, so `{"level":2}` can be omitted. An anchor goes in the HTML `id`; `{"anchor":"my-section"}` in the block comment also works and survives round trips through the editor better. ```html

Section heading

``` ### Font sizes write two classes A `fontSize` attribute writes the Gutenberg class and a paired Mangrove utility class from a fixed map, so the markup also renders correctly where Mangrove CSS is loaded without the Gutenberg styles: | `fontSize` | Saved classes | | --- | --- | | `small` | `has-small-font-size mg-u-font-size-250` | | `regular` | `has-regular-font-size mg-u-font-size-300` | | `medium` | `has-medium-font-size mg-u-font-size-400` | | `large` | `has-large-font-size mg-u-font-size-500` | | `huge` | `has-huge-font-size mg-u-font-size-800` | On `wp:buttons`, Gutenberg also adds `has-custom-font-size`. ```html

Page title

``` Older pages set `{"className":"has-large-font-size"}` on paragraphs instead. That still renders, but new content should use the `fontSize` attribute from the editor's typography panel. ### Buttons carry Mangrove classes `wp:button` writes the core `wp-element-button` class and a Mangrove button class. The default style maps to `mg-button-primary`; the **Outline** style maps to `mg-button-secondary`. `mg-button-arrow` appears only in the hero block's own buttons, never in `wp:button`. ```html
Primary action
Secondary action
``` `is-style-primary is-style-outline` together still produce `mg-button-secondary`; the outline style wins. ### Lists `wp:list` is saved with an explicit `className` even though `wp-block-list` is its default, and every item needs its own `wp:list-item` wrapper. Bare `
  • ` elements fail validation. ```html
    • First item
    • Second item with a link
    ``` ### Separators and spacers ```html
    ``` ### Images from the media library An image inserted from the Drupal media library records the Drupal file in a `mediaAttrs` object and mirrors it as `data-*` attributes on the ``. Captions use `wp-element-caption`. ```html
    Alt text
    Caption. Photo: UNDRR
    ``` When drafting without a real media item, use a placeholder `src` and leave out `mediaAttrs`; the editor fills them in when an image is chosen. Image paths start with `/sites/default/files/`. A Drupal `public://` path becomes `/sites/default/files/`, and spaces in file names are URL-encoded. ### Media URLs are not stored in the block comment For `undrr/undrr-card` and `undrr/undrr-hero-block`, `mediaURL` is read back from the `src` of the saved ``, so it does not belong in the block comment; the editor drops it there on the next save. `mediaID` and the alt text attribute (`mediaAlt` on cards, `mediaAltText` on heroes) do belong in the comment. ### Special characters In the JSON block comment, characters can be written literally when pasting: `"Climate & Disaster"`. In the saved HTML, use entities: `Climate & Disaster`, which matches what the blocks' `save()` functions produce. When the editor saves, it escapes `<`, `>`, `&` and `"` inside attribute values as Unicode sequences (`\u003c`, `\u003e`, `\u0026`, `\u0022`), so an attribute that holds HTML, such as a hero `summaryText` with a link, reads `\u003ca href=\u0022…\u0022\u003e` in the block comment. Write it that way when composing by hand: an unescaped `"` inside an attribute value ends the JSON string and breaks the block. ### Section wrappers use columns, not groups `wp:group` breaks when it is used as a standalone section or background wrapper. Use `wp:columns` with a single `wp:column` child instead: ```html
    [section content]
    ``` One exception works: `wp:group {"layout":{"type":"constrained"}}` nested inside a `wp:column` of such a wrapper, which holds the section content to the default content width without percentage columns. [Building landing pages](#section-backgrounds) shows both. ## Rendering constraints Valid markup can still render wrongly because of the Mangrove CSS and scripts a site loads. Several limits of older builds are fixed in current Mangrove, so check which Mangrove version the site loads before applying a workaround. Page-level CSS goes in a `wp:html` block containing a `Show more ``` [Building landing pages](#show-more) has the full layout with the target block. ### Scroll container `undrr/undrr-scroll-container` renders a [Scroll container](https://mangrove.undrr.org/?path=/docs/components-scrollcontainer--docs) around its inner blocks. Each direct child becomes one scroll item. | Attribute | Default | Effect | | --- | --- | --- | | `itemWidth` | `auto` | Width of each item. Set a value such as `"300px"`, or items shrink to their content | | `stepSize` | `300` | Pixels scrolled per arrow click. Set it a little larger than `itemWidth` so a click advances one item and the gap | | `showArrows` | `true` | Previous and next buttons | | `height`, `minWidth`, `padding` | `auto`, `auto`, `0` | Row height, minimum item width, inner padding | | `ariaLabel` | Empty | Accessible name for the row, such as "Publications" or "Partners"; saved as `data-aria-label` only when set | The six layout attributes are saved as `data-*` attributes whether or not they differ from the default. Name every scroll container, so screen reader users can tell one collection from another. ```html
    [inner blocks]
    ``` ### Highlight box `undrr/highlight-box` renders a [Highlight box](https://mangrove.undrr.org/?path=/docs/components-highlightbox--docs) around its inner blocks. `tone` is `default`, `primary` or `secondary`; `layout` is `full` (default), `centered`, `float-start` or `float-end`. Non-default values add `mg-highlight-box--{value}`. ```html

    Did you know?

    [One short fact, with its source.]

    ``` ### Quote highlight `undrr/undrr-quote-highlight-block` renders a [Quote highlight](https://mangrove.undrr.org/?path=/docs/components-quotehighlight--docs). Attributes: `attribution`, `attributionTitle`, `imageSrc`, `imageAlt`, `backgroundColor` (`light` or `dark`), `variant` (`line` or `image`) and `alignment`. The quote itself is inner paragraph blocks. ```html

    Disaster risk reduction is everyone's business. It requires the engagement of all sectors and all people.

    Name Surname

    Title and organization

    ``` For a pull quote with no attribution, a lighter pattern is in [Building landing pages](#quotes). ### Social share `undrr/undrr-social-share-block` has no attributes and renders [Share buttons](https://mangrove.undrr.org/?path=/docs/components-buttons-sharebuttons--docs). ```html ``` ### Search widget `undrr/search-widget` renders the [Syndicated search](https://mangrove.undrr.org/?path=/docs/components-syndicated-search--docs) widget. The block writes around 20 `data-*` attributes on a container with `data-undrr-search-widget="true"`, and a wrapper script in the Drupal theme reads them and mounts the Mangrove component. Mangrove's own hydration does not read that attribute; it is specific to the platform wrapper. Widgets saved before [undrr/web-backlog#2822](https://gitlab.com/undrr/web-backlog/-/work_items/2822) keep **Override with current website domain** and **Override with current page language** off through the block's deprecation; new widgets have both on. Configure it in the block sidebar rather than by hand; [Search widget editor configuration](https://mangrove.undrr.org/llms-search-widget.txt) documents every setting and the filter syntax, and has the [saved markup](https://mangrove.undrr.org/llms-search-widget.txt#saved-markup) of a new widget. ### Core blocks used alongside the UNDRR blocks **Video.** Use `wp:embed` with the ordinary watch URL; the Gutenberg text format swaps it for the player at render time. Put the caption in a paragraph after the embed, not in a `
    `. ```html
    https://www.youtube.com/watch?v=VIDEO_ID

    Caption. Video: UNDRR

    ``` **Drupal media.** `drupalmedia/drupal-media-entity` embeds a media entity (image, video or document) and is self-closing, because the server renders it. `viewMode` is a Drupal image style: `ultrawide_16_6`, `landscape_16_9`, `portrait_3_4`, `thumbnail` or `full`. A video media entity is worth it when the same video appears on several pages; for a one-off, `wp:embed` needs no media entity. ```html ``` **Page-level CSS.** A `wp:html` block with a `