Stop guessing your Drupal module README.md , there is a free custom GPT for that
Stop guessing your Drupal module README.md content/structure/specifications: There is a free custom GPT for that :)
If you’ve maintained a Drupal module long enough, you’ve probably had this moment:
You open your module’s README.md and think… “Okay, what is this file supposed to contain again?”
Not “what could it contain”, but what it should contain so that it matches Drupal.org expectations, feels professional, and doesn’t trigger endless reviews.
That exact friction is why I built Drupal™ README.md Optimizer, a custom GPT focused on rewriting and restructuring Drupal module READMEs to align with Drupal.org’s documentation standards.
Drupal™ README.md Optimizer (ChatGPT Store):
https://chatgpt.com/g/g-6942cfbce004819180a2ba8e83df8a0d-drupaltm-readme-md-optimizer
The “official” Drupal README standard (and why it matters)
Drupal.org actually provides a recommended README.md structure (and even formatting guidance). The template isn’t just about being tidy, it’s about helping users quickly answer the questions that decide whether your module gets installed:
- What does it do?
- What does it depend on?
- How do I install it?
- How do I configure it?
- Where do I get help?
- Who maintains it?
Drupal’s README.md template recommends a consistent set of sections, including (among others): Project name & introduction, Requirements, Installation, Configuration, and optional sections like Recommended modules, Troubleshooting & FAQ, and Maintainers.
It also calls out formatting details (like heading style, meaningful links, and wrapping text around ~80 columns) to keep documentation readable and consistent across projects.
And Drupal’s module documentation guidelines reinforce that the README should mirror the project synopsis and that larger install/config instructions can be moved into a dedicated INSTALL.md when needed.
Side note: why I wrote this GPT in the first place
I’ve never been fully sure what should be inside a README.md, not because I don’t write documentation, but because the “expected shape” of a Drupal README is a mix of habit, tribal knowledge, and scattered examples across contrib.
At some point I just thought: “Instead of re-learning this every time, why not bake the Drupal guidelines into a custom GPT and make it reusable?”
That’s basically the whole origin story :)
Why I needed it?: Drupical + Drupal CMS v2.0
The immediate trigger was practical: I needed to rewrite the README for our module, Drupical, because it’s intended to be part of Drupal CMS v2.0 🚀🎉💙.
So: real release pressure, real review cycles, and a README that needed to be crystal clear.
In the end, this was the README that was restructured with the custom GPT:
https://git.drupalcode.org/project/drupical/-/blob/d47537a2762b1e5397308274977742151972e9ce/README.md
Back to the main Topic:
What the custom GPT actually helps with
Custom GPTs are essentially tailored versions of ChatGPT that combine instructions (and optionally knowledge) to do one job consistently.
In this case, the job is:
- Rewrite an existing README in clearer language (without losing meaning)
- Restructure it into the Drupal-recommended sections
- Spot missing pieces (and mention this in the output, so the user of the custom GPT will know there is something to still work on)
The biggest win isn’t “AI writes my docs.” It’s:
I stop starting from a blank page and stop arguing with myself about structure.
If a readme has to be done from scratch, put everything interesting in the text, the custom GPT will do the rest, and help you to refine/restructure everything and also writes what's missing.
But even if it writes it, … the “correct” section order each time. etc. it helps also with writing new readmes. puke everything inside of the gpt, and magic happens.
How to use it (my workflow)
- Paste your current README.md (even if it’s messy).
- the custom GPT will instantly start to restructure it markdown formatted.
- Treat the output as a draft:
- Verify technical accuracy (requirements, steps, UI paths).
- Fill in any placeholders (especially configuration and troubleshooting).
- Commit, and enjoy a README that looks like it belongs in contrib.
A quick caution (because it’s AI)
A GPT can help you structure and rewrite, but it can still:
- assume details you didn’t provide,
- miss project-specific edge cases,
- or phrase something too confidently.
So I treat it like an assistant that’s great at format + clarity, while I remain responsible for the outcome.
Shameless plug: like with our AI Sidekick tool. Editors should be always in control, but brainstorming and help for “boring” tasks is a gamechanger.
Wrap-up
This GPT exists because I hit the same wall repeatedly: “What should be in this README?”
Drupal.org has the answers, but remembering and applying them every time is annoying.
So I packaged that standard into a reusable tool, used it on a real module README under real constraints, and made it available, so others can skip the same friction.
If you try it, and it saves you even one round of README bike shedding, it’s already doing its job.