FAQ and Troubleshooting

For end users and support teams. Answers are based on the module's actual behaviour.

FAQ

What exactly does this module display?

It displays the Markdown file dashboard.md that lives in a GitHub repository's stats folder. That file typically contains Shields.io badges, generated SVG trend charts and a data table. The module renders that content; it does not generate statistics itself.

Does the module track my visitors or collect analytics?

No. It does not collect, store or transmit any visitor data and has no telemetry. It only reads statistics that already exist in a GitHub repository and displays them.

Do I need any other Joomla extension?

No. There are no third-party Joomla dependencies. Marked.js and DOMPurify are loaded from a CDN at runtime.

Free or paid?

Free and open source, licensed under the GNU GPL v3 or later.

Which Joomla and PHP versions are supported?

Joomla 5.0 or later (Joomla 5 and Joomla 6) and PHP 8.1 or later.

Is it compatible with Joomla 3 or Joomla 4?

No. The module targets Joomla 5 and Joomla 6 only. Joomla 3 and Joomla 4 are not supported.

Single repository vs. grid - how is that decided?

Automatically, by the number of entries in the Modules list:

One entry switches to a single-article layout and renders the dashboard directly on the page (no card, no modal).
Two or more entries render a grid of clickable cards that open a modal. The Grid columns setting supports 1 to 7; a 1-column grid stacks full-width cards that still open the modal.

Can I mix different repository owners or branches?

The Repository owner and Branch are global, so all entries share them. Each entry in the list is a repository name under that owner.

How fresh is the data?

As fresh as the dashboard.md in the repository. The module re-fetches when the browser cache TTL expires (default 30 minutes). Shields.io badges have their own cache (about 15 minutes), so they can lag slightly.

Where is the data cached?

In the browser's localStorage, keyed per module, repository and branch. Nothing is cached on the server. Set Cache TTL (minutes) to 0 to disable client caching.

Does it work with a template override?

Yes. Standard Joomla template overrides apply, and the Alternate Layout and Module Class Suffix options are available.

Troubleshooting

Nothing shows / "Failed to load stats" appears

Confirm the raw URL is reachable. Open the browser Network tab and look for the request to raw.githubusercontent.com/.../<stats-folder>/dashboard.md.
A 404 means the raw file could not be found. It can come from a wrong path (Repository owner, repository name, Branch or Stats folder) or from the repository not having a dashboard.md at all - both look identical to the browser. Check the path first, then confirm the file exists (see "Stats coming soon" below).
A network or CORS-style failure can indicate the site (or a proxy/firewall) is blocking outbound HTTPS to raw.githubusercontent.com or to the CDNs.
Make sure Marked.js and DOMPurify are not blocked; if either fails to load the module reports the fetch error.

Badges and charts do not appear, but text does

The Markdown rendered, so the issue is with the referenced assets.

Relative image paths such as charts/total-trend--black.svg are rewritten against the raw stats folder. If they 404, the file must actually exist in that repository folder (stats/ by default, or whatever the Stats folder is set to).
Check the rewritten URL in the browser developer tools (Inspect the <img> element) and confirm the file exists on GitHub at that path.
Absolute URLs (Shields.io badges, full raw.githubusercontent.com URLs) are left unchanged and work as long as those services are reachable.
Shields.io badges can appear blank if the badge service is rate-limited or unreachable; this is outside the module's control.

The grid shows the wrong number of columns

Set Grid columns to a value from 1 to 7; values outside the supported range fall back to 5. The single-repository (single-article) layout always uses the full width and ignores this setting.

Charts look stale after a repository update

The browser cache is still serving an earlier render. Wait for the TTL to expire, or lower Cache TTL (minutes), or clear the site's localStorage entry for bearsampp-stats:v2:.

Icons do not show on the cards

Make sure Show stats icon is set to Yes.
If you entered a Font Awesome code in Stats icon (FA code), your template must load Font Awesome. Leave the field empty to use the built-in SVG icon instead.

The modal does not open

Grid/modal mode relies on Bootstrap 5. Confirm your template loads Bootstrap 5 JavaScript. The single-repository (single-article) layout does not use the modal.

"Stats coming soon for this module"

This is the graceful fallback shown when a repository has no dashboard.md. The stats workflow normally creates that file automatically - re-run stats-daily-with-chart (Actions → Run workflow) or wait for the daily run, and the dashboard will appear. If you author your own file instead, add it to the stats folder (or fix the path/branch).

The dashboard heading is wrong

The module replaces the first Markdown heading with # <repository> Statistics and retargets the link text in the "Release asset download totals for [...]" line at the actual repository. The default file generated by the workflow starts with # <repo> Downloads, so the two are shown consistently. If your dashboard.md has a different heading or no description line, the original wording is shown as-is - which is harmless.

General debugging tips

Open the browser developer tools Console - the module logs Bearsampp Stats fetch error: with the underlying cause.
Check the Network tab for the dashboard.md request and any chart asset requests.
Verify the exact raw URL in a new browser tab; it should return the Markdown text.
Temporarily set Cache TTL (minutes) to 0 to rule out stale cache.