drupal-project-description

name	drupal-project-description
description	Use when creating or editing a project page/description on drupal.org (the module or theme body at drupal.org/project/<name>), generating a PROJECT_DESCRIPTION.html file, or formatting a Drupal.org project page with headings, note boxes, tip boxes, action buttons, grids, and side-by-side link listings.

Drupal.org Project Description

Overview

Drupal.org project pages (drupal.org/project/<name>) render a restricted subset of HTML. This skill generates or edits that body HTML, saved as an .html file the maintainer pastes into the project's description field. It also knows the special CSS classes drupal.org ships that make a page pop: checkered note boxes, tip boxes, green buttons, grids, and side-by-side listings.

Core rules

• The first element is always one <p> describing what the project does. This becomes the preview text in module listings and search results. No heading before it.
• Only use the allowed HTML (below). Anything else is stripped on save.
• Enhance with the special classes, but don't overdo it; they highlight focused content.

Writing Style

The description should read like a maintainer wrote it, not like an AI generated it. Apply these rules to all prose in the description.

• No em dashes and no en dashes anywhere. Use a comma, semicolon, colon, period, or parentheses, or rewrite the sentence. Plain hyphens are fine only in compound words (e.g. site-builder).
• Active voice.
• Wry, plain, and direct. No flowery or superfluous language.
• No contrastive constructions such as "this isn't X, it's Y." State what the thing is.
• No rhetorical negation such as "not optional, it's required." Just state the point.
• No marketing hype, subjective qualifiers, or value judgments. State facts a user can verify.
• No emojis or icons in the prose.
• Keep it terse and high in signal. Cut padding and throat-clearing intros.

Workflow

1. Ask where the file goes. Default is the project's module folder as PROJECT_DESCRIPTION.html (e.g. web/modules/contrib/<name>/PROJECT_DESCRIPTION.html, or the module root). Always confirm the path before writing; don't assume.

2. Editing an existing page? Read the live page first. The data name is the last URL segment (drupal.org/project/ai gives ai):

   curl -sL "https://www.drupal.org/project/<dataname>" -o page.html
   

   The description body is the rendered content region. Preserve the maintainer's existing structure and voice; make the requested edits rather than rewriting wholesale.

3. New project? Include these headings (as <h2>), in this order, skipping any that don't apply:

   • Features
   • Installation
   • Related Modules, only if any exist. Find them by searching the module list at https://www.drupal.org/project/project_module for modules similar to this one (same job or alternatives), not modules that share its ecosystem or project family. Use an <h3> for this heading, not an <h2>, and keep the heading outside any special div. A special div (such as view-book-listings) can follow underneath the <h3>, never wrapping it.
   • Requirements/Dependencies, only if any exist. Do not list Drupal core or PHP version unless the requirement is unusual (e.g. a specific PHP extension, a non-obvious version constraint).

4. Write the HTML to the confirmed path using the elements and components below.

5. Screenshots (optional). If the module is installed on a site you can reach and you have agent browser access, take a few screenshots of the feature in action to embed as <img>. Skip silently if either isn't available; don't fabricate image URLs.

Allowed HTML

Headings <h2> to <h4>, <p>, <strong>, <em>, <i> (cursive), <code>, <blockquote>, <img>, <a>, <ul>/<ol>/<li>, <table>, <del> (strikethrough), <hr>.

Special Components

Copy these patterns exactly. The classes are what trigger the styling.

Note / version box: checkered paper background, for focused callouts

<div class="note-version">
<h2>For Marketers, Business Owners and Decision Makers</h2>
<p>One focused paragraph. Use <strong>bold</strong> for the key phrases.</p>
</div>

Tip box: grey background with a light-bulb icon on the left

<div class="note-tip">
<h3>Discover the benefits</h3>
<p>Short explanation of the tip or next step.</p>
<p><a href="https://example.com" class="action-button" rel="nofollow">Learn more</a></p>
</div>

Warning box: yellow background with an exclamation mark, for important warnings

<div class="warning">
<p>Important note the reader should not miss (breaking change, required config, security caveat).</p>
</div>

Action button: green call-to-action button (an <a>, usually wrapped in a <p>)

<p><a href="https://example.com" class="action-button" rel="nofollow">Get the Module</a></p>

Grid: half (50%) or third (33%) columns, each cell a grey note box

<table class="view-view-grid">
<tbody>
<tr>
<td width="50%"><div class="note"><h3>Column one</h3><p>Text.</p></div></td>
<td width="50%"><div class="note"><h3>Column two</h3><p>Text.</p></div></td>
</tr>
</tbody>
</table>

Use width="33%" across three <td> cells for a three-column row.

Book listing: heading plus intro, a rule, then side-by-side (50%) links

Each <li> in ul.guide-contents renders at half width, so links or items sit two per row.

<div class="note view-book-listings">
<h4>Providers</h4>
<p>Supported integrations, side by side.</p>
<hr>
<ul class="guide-contents">
<li><a href="https://www.drupal.org/project/provider_a" rel="nofollow">Provider A</a></li>
<li><a href="https://www.drupal.org/project/provider_b" rel="nofollow">Provider B</a></li>
</ul>
</div>

Structure Tips

• Separate major sections with <hr>.
• Lead each note-version / note-tip with its own <h2>/<h3> so the box has a clear title.
• External links should carry rel="nofollow".
• A complete skeleton for a new project lives in example.html. Adapt it; don't ship it verbatim.

Common Mistakes

Mistake	Fix
Starting with a heading	First element must be one <p> preview paragraph.
Prose that reads like AI (em dashes, hype, contrastive phrasing)	Follow the Writing Style rules above.
Listing Drupal core / PHP under Requirements/Dependencies	Omit unless the constraint is unusual.
Using unsupported tags (<span>, <div style>, classes not listed)	Stripped on save; stick to the allowed set and named classes.
Overusing note boxes	They highlight focus; a page that's all boxes highlights nothing.
Guessing image URLs	Only embed images you actually captured or that already exist.
Writing the file without asking where	Confirm the output path first (default PROJECT_DESCRIPTION.html in the module folder).