DEV Community

Fernando Paladini
Fernando Paladini

Posted on

Curate Verifiable ActiveAdmin 4 Themes with Markdown and CI

#ruby #rails #tutorial #activeadmin

When a Rails theme claims ActiveAdmin 4 support, the difficult part is often not finding a screenshot. It is checking whether the theme actually targets ActiveAdmin 4's Tailwind-based asset model, whether the installation commands are current, and whether the claim can be reviewed later.

This tutorial shows how to build that review workflow with activeadmin-v4-themes, an MIT-licensed directory that curates documented ActiveAdmin 4 themes. The repository stores documentation and links, not third-party theme code. You will inspect its evidence standard, add a candidate entry, and run the same kinds of local checks used by its CI.

TL;DR

Use a small Markdown repository as a compatibility index, but require evidence before adding a theme. For each candidate, record the public source URL, license, ActiveAdmin 4 version range, asset and styling requirements, installation commands, screenshots or demo, and known limitations. Then run link checking and Markdown linting before opening a pull request.

Prerequisites

You need:

  • Git
  • Node.js and npx
  • A public theme repository to evaluate
  • Enough familiarity with Rails and ActiveAdmin to understand its asset pipeline

The directory itself is not a Ruby gem and does not install ActiveAdmin. Its current main README describes a documentation workflow, and its pyproject.toml equivalent does not exist because the project has no package manifest. The repository currently has no versioned release, so the commands below target the current main documentation checked on September 30, 2026.

1. Clone the directory and inspect the standard

Start from the public repository:

git clone https://github.com/paladini/activeadmin-v4-themes.git
cd activeadmin-v4-themes
Enter fullscreen mode Exit fullscreen mode

The current README defines a narrow scope: entries must have documented, verifiable ActiveAdmin 4 support. Legacy ActiveAdmin 3 and SCSS-only themes do not belong in the main list. That distinction is important because a visual match does not prove compatibility with the newer Tailwind-based interface.

Read the contributor checklist before evaluating a project:

less CONTRIBUTING.md
Enter fullscreen mode Exit fullscreen mode

On Windows PowerShell, use:

Get-Content .\CONTRIBUTING.md
Enter fullscreen mode Exit fullscreen mode

The contribution guide asks you to confirm public source code and an open-source license, verify the ActiveAdmin 4 version range, check the asset and styling model, and document installation, screenshots, and limitations. It also says not to copy third-party source code or screenshots into the directory.

2. Turn a compatibility claim into evidence

Before writing a README entry, inspect the theme's own primary sources. A useful evidence record answers five questions:

  1. Where is the public source repository?
  2. Which license covers the theme?
  3. Which ActiveAdmin 4 version or range is named?
  4. Does the installation path use the ActiveAdmin 4 asset and styling model?
  5. Is there a test, demo, screenshot, or maintainer statement that supports the claim?

The repository's issue template turns those questions into required fields. Open the template in your browser or inspect it locally:

cat .github/ISSUE_TEMPLATE/new-theme.yml
Enter fullscreen mode Exit fullscreen mode

The required fields include the project URL, ActiveAdmin version support, compatibility evidence, and exact installation commands. This is a practical design choice: a maintainer can review structured evidence before editing the curated list.

For example, the current entry for activeadmin-claude-theme names ActiveAdmin 4.0.0.beta22+, Tailwind CSS v4, and a Rails Engine generator. Its installation snippet is:

gem "activeadmin-claude-theme"
Enter fullscreen mode Exit fullscreen mode 
bundle install
rails generate activeadmin_claude_theme:install
npm run build:css
Enter fullscreen mode Exit fullscreen mode

The entry also states that the application must already use ActiveAdmin 4 with Tailwind v4 assets. That limitation belongs beside the install commands because it changes whether a reader can use the theme in an existing Rails app.

3. Add a concise, reviewable entry

The directory uses ordinary Markdown rather than a custom database. A new entry should be short enough to scan but detailed enough to verify. Give it a descriptive heading, a one-sentence summary, and a small table with these fields:

  • Project and canonical source URL
  • License
  • ActiveAdmin version range
  • Styling and asset model
  • Rails integration method
  • Verification status

Follow the table with an Install heading containing the exact commands, then a Known limitations heading. For example, the current entry uses bundle install, rails generate activeadmin_claude_theme:install, and npm run build:css as separate commands rather than hiding setup in prose.

Keep the links pointed at the original project. The directory's purpose is to make compatibility easier to inspect, not to become a mirror of someone else's code.

4. Run reproducible checks before review

The contributor guide documents the local link check:

npx --yes markdown-link-check README.md
Enter fullscreen mode Exit fullscreen mode

The repository's GitHub Actions workflow runs that check together with Markdown linting. You can run both locally with:

npx --yes markdown-link-check README.md
npx --yes markdownlint-cli2 "**/*.md"
Enter fullscreen mode Exit fullscreen mode

On the current checkout, the link checker reported 22 successful links and the Markdown linter reported zero issues across five Markdown files. Those results are verification of the directory snapshot, not proof that every listed theme works in every Rails application.

If a link check fails, fix the source URL or remove the claim. Do not replace a dead primary source with a search result or an unrelated mirror. If the theme's ActiveAdmin 4 support cannot be demonstrated, leave it outside the curated list and explain what evidence is missing in the issue or review.

Why this works

Compatibility directories become useful when they separate discovery from certification. A reader can discover a candidate from the list, then follow the project link to inspect its own code and installation guide. The directory adds a second, reviewable layer: version claims, asset assumptions, screenshots or demos, and limitations are visible in one place.

The repository also keeps its security boundary small. Its security policy says it contains documentation and links to external projects. It does not ship third-party theme code or application credentials. That means a contribution cannot silently add a copied dependency or a secret-bearing example to the index.

Failure modes and honest limits

A screenshot looks right, but the integration is legacy

A polished screenshot does not establish ActiveAdmin 4 support. Check whether the project documents the ActiveAdmin 4 Tailwind architecture rather than only importing the classic active_admin/base SCSS stylesheet.

The version claim is too broad

Write the narrowest range supported by primary evidence. The current directory notes that ActiveAdmin 4 is still a beta series and tells readers to confirm the upstream compatibility range before production use. Treat that as a compatibility warning, not as a promise of production readiness.

The install command hides prerequisites

Commands such as rails generate may assume an existing Rails application, ActiveAdmin, CSS bundling, import maps, or a specific Node setup. Put those prerequisites in the entry instead of presenting a partial command as a complete installation.

A listed theme changes after review

The directory is a snapshot, not a live compatibility oracle. Recheck the source repository, release notes, tests, and installation guide when upgrading ActiveAdmin or choosing a theme for a real application.

FAQ

Does this repository install themes?

No. It curates documentation and links. Installation remains the responsibility of each theme's own repository.

Can an ActiveAdmin 3 theme be listed?

Not in the main ActiveAdmin 4 list unless its current documentation verifies ActiveAdmin 4 compatibility. The README explicitly excludes legacy ActiveAdmin 3 and SCSS-only themes from that scope.

Is Markdown linting enough to approve a theme?

No. Linting checks document structure. It does not prove license ownership, version compatibility, asset behavior, or security properties. Those require primary-source review.

Takeaway

A small Markdown directory can provide real engineering value when every entry has a clear evidence threshold. For ActiveAdmin themes, verify the version, asset model, installation path, and limitations first. Then keep the record concise, link to the original project, and run link and Markdown checks before review.

This article was prepared with AI assistance for research organization and drafting. Repository facts, commands, and validation results were checked against the current public project sources and a local checkout.

What evidence would you require before trusting a compatibility directory for another Rails ecosystem?

Top comments (0)