feat: publish the documentation and the card wizard from one Astro site by marcalexiei · Pull Request #489 · stats-organization/github-stats-extended

marcalexiei · 2026-08-16T23:09:19Z

Closes Publish documentation from release instead of master #461

Turns apps/frontend into an Astro + Starlight site.
Serves the docs at /frontend/docs and the card wizard at /frontend:
one dev server, one build, one deploy, and no Python in vercel-preparation.sh or in the local setup.
The wizard becomes a page of that site: a React island on Starlight's splash layout,
so it inherits the header, footer and search.
Its own app bar, theme picker and Redux theme slice go away.
Starlight writes the data-theme daisyUI already reads, so one control themes both halves.
The *.md sources move to apps/frontend/src/content/docs/docs/ with a title in
frontmatter and Starlight's :::note asides, which lets Astro resolve their links and
images natively (no markdown-conversion code of our own).
starlight-links-validator then fails the build on a dead internal link.
packages/core/src/themes/README.md is generated into the site instead; README and CONTRIBUTING links follow the move.
Tailwind now shares a page with Starlight, so index.css declares the cascade-layer order
(its utilities must outrank Starlight's reset) and scopes the app's element rules under
.wizard, leaving the site chrome identical on both halves.

To try it out just run

pnpm --filter ./apps/frontend run dev

Wizard	Documentation

vercel · 2026-08-16T23:09:25Z

@marcalexiei is attempting to deploy a commit to the martin-mfg's projects Team on Vercel.

A member of the Team first needs to authorize it.

vercel · 2026-08-18T14:36:54Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
github-stats-extended-backend	Ready	Preview	Aug 19, 2026 8:09am

marcalexiei · 2026-08-19T02:21:24Z

I made few changes with the last commit (totally fine if you want to go ahead without them):

Splits the "Advanced Customization" page into smaller pages, grouped in the sidebar under two categories:
- Cards: one page per card
- Customization: Common Options, Theming, Available Themes, Locales and Aligning Cards
Moved the options shared by every card out from under "GitHub Stats Card", where they were nested despite applying to all of them.
Redirects /frontend/docs/advanced_documentation/ to "Common Options" and both group paths to their first page, so published URLs do not hit 404.
Links each card title in the Overview page's "Card Types" section to that card's page.

martin-mfg

I haven't completely reviewed all changes yet. But I reviewed most of them and don't want to keep you waiting longer for initial feedback.

Btw, good idea to go with Astro+Starlight instead of MkDocs. 👍

martin-mfg · 2026-08-18T09:07:30Z

+ * Pages the wizard links to, named by the slug Starlight serves them under.
+ * Typed so renaming or dropping one turns every stale link into a compile error.
+ *
+ * @todo extract them statically from the config or other astro exports to build this dynamically.


This should stay a todo for now?

Yes, I'll deal with this separately. There is already too much content here.

martin-mfg · 2026-08-18T11:39:54Z

Would it make sense to move packages/core/scripts two levels up, since this is not core-related anymore?

Sure, I moved it.
I'm thinking about do the same with all scripts across the repo so we can have them all in one place.

martin-mfg · 2026-08-18T14:23:23Z

I think the links in this file should point to https://github-stats-extended.vercel.app/frontend/docs/..., because the target *.md files are not supposed to be read on GitHub anymore.

Done, all point at https://github-stats-extended.vercel.app/frontend/docs/....

Also fixed an unrelated stale link: ../backend/src/translations.js ➡️ ../packages/core/src/translations.ts.

martin-mfg · 2026-08-18T16:47:30Z

-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <link rel="icon" href="/favicon.ico" />


We're losing the favicon here. Not sure if any of the other stuff below is important.

I restored the previous tags and the favicon now points the correct path.

martin-mfg · 2026-08-19T07:45:30Z

-We use caching to decrease the load on our servers (see <https://github.com/anuraghazra/github-readme-stats/issues/1471#issuecomment-1271551425>). Cards generated by [https://github-stats-extended.vercel.app/](https://github-stats-extended.vercel.app/frontend) are cached for a few hours or days, depending on server load. If you want the data on your cards to be updated more often you can [deploy your own instance](/frontend/docs/deploy/) and set [environment variable](/frontend/docs/deploy/#available-environment-variables) `CACHE_SECONDS` to a value of your choosing. Or you can use the [GitHub Action workflow](https://github.com/stats-organization/github-readme-stats-action).
+We use caching to reduce the load on our servers (see [this discussion](https://github.com/anuraghazra/github-readme-stats/issues/1471#issuecomment-1271551425)).
+
+Cards generated by [GitHub Stats Extended](https://github-stats-extended.vercel.app/frontend) are cached for a few hours to several days, depending on the current server load.


Cards generated by [GitHub Stats Extended]

The text should make it clear that the caching explanation only applies to our public deployment at github-stats-extended.vercel.app. Because self-hosted instances, the grs-action and using the npm package directly may behave differently.

Updated (I haven't update the text here, it's written this way in master).

martin-mfg · 2026-08-19T07:47:27Z

-We use caching to decrease the load on our servers (see <https://github.com/anuraghazra/github-readme-stats/issues/1471#issuecomment-1271551425>). Cards generated by [https://github-stats-extended.vercel.app/](https://github-stats-extended.vercel.app/frontend) are cached for a few hours or days, depending on server load. If you want the data on your cards to be updated more often you can [deploy your own instance](/frontend/docs/deploy/) and set [environment variable](/frontend/docs/deploy/#available-environment-variables) `CACHE_SECONDS` to a value of your choosing. Or you can use the [GitHub Action workflow](https://github.com/stats-organization/github-readme-stats-action).
+We use caching to reduce the load on our servers (see [this discussion](https://github.com/anuraghazra/github-readme-stats/issues/1471#issuecomment-1271551425)).
+
+Cards generated by [GitHub Stats Extended](https://github-stats-extended.vercel.app/frontend) are cached for a few hours to several days, depending on the current server load.


depending on the current server load

This sounds like we have a some dynamic logic in place for caching duration. In reality I have manually adapted the cache timing a few times over the past month.

Adjusted the text (I haven't update the text here, it's written this way in master).

martin-mfg · 2026-08-19T08:01:11Z

In both examples on this page, the cards are actually shown below each other, which defeats the purpose:

Could we use narrower cards here or get them into the same row in another way?

Should be good to go now

martin-mfg · 2026-08-19T08:03:03Z

+## Responsive Card Theme
+
+[![Anurag's GitHub stats-Dark](https://github-stats-extended.vercel.app/api?username=anuraghazra&show_icons=true&theme=dark#gh-dark-mode-only)](https://github.com/stats-organization/github-stats-extended#responsive-card-theme#gh-dark-mode-only)
+[![Anurag's GitHub stats-Light](https://github-stats-extended.vercel.app/api?username=anuraghazra&show_icons=true&theme=default#gh-light-mode-only)](https://github.com/stats-organization/github-stats-extended#responsive-card-theme#gh-light-mode-only)


The theming via #gh-dark-mode-only/#gh-light-mode-only doesn't work here.

The section header now uses <picture>, and the GitHub-only technique says why it has no live preview.
The copyable snippet is unchanged.

…ources

…mple

feat: publish the documentation and the card wizard from one Astro site

54c23d8

marcalexiei force-pushed the docs-frontend-astro branch from 7e9adf6 to 54c23d8 Compare August 16, 2026 23:15

marcalexiei mentioned this pull request Aug 16, 2026

Publish documentation from release instead of master #461

Open

vercel Bot had a problem deploying to Preview – github-stats-extended-backend August 18, 2026 14:37 Failure

fix failing deployment due to missing md files

a91bef3

vercel Bot deployed to Preview – github-stats-extended-backend August 18, 2026 16:04 View deployment

docs(advanced_documentation): fix incorrect github action link

2c8419c

marcalexiei force-pushed the docs-frontend-astro branch from e7c4022 to b91a859 Compare August 19, 2026 02:16

marcalexiei requested a review from martin-mfg August 19, 2026 02:21

docs: split the Advanced Customization page into focused pages

05538de

marcalexiei force-pushed the docs-frontend-astro branch from b91a859 to 05538de Compare August 19, 2026 02:40

vercel Bot deployed to Preview – github-stats-extended-backend August 19, 2026 08:09 View deployment

martin-mfg requested changes Aug 19, 2026

View reviewed changes

marcalexiei added 6 commits August 19, 2026 14:18

chore(frontend): use caret ranges for astro and starlight

ae21ab5

chore(frontend): replace deprecated rollupOptions with rolldownOptions

743c84c

chore(frontend): drop redundant DOM.Iterable lib

1e20e81

docs(contributing): link the published docs instead of the markdown s…

1f6755c

…ources

fix(frontend): make the delete modal backdrop dim the whole page

38401f6

fix(frontend): restore the favicon, touch icon and web manifest

cfc85a5

marcalexiei force-pushed the docs-frontend-astro branch from 2b20bc5 to 24b8c19 Compare August 19, 2026 12:40

marcalexiei added 4 commits August 19, 2026 14:43

docs(customization): scope the caching note to the public deployment

bda98b3

docs(theming): stop showing GitHub-only theme switching as a live exa…

338eeed

…mple

docs(aligning-cards): render the examples side by side

7bdf536

chore: move the theme readme generator to the repo-level scripts folder

bc40152

marcalexiei force-pushed the docs-frontend-astro branch from 24b8c19 to bc40152 Compare August 19, 2026 12:43

Uh oh!

Uh oh!

Conversation

marcalexiei commented Aug 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vercel Bot commented Aug 16, 2026

Uh oh!

vercel Bot commented Aug 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

marcalexiei commented Aug 19, 2026

Uh oh!

martin-mfg left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

marcalexiei Aug 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

marcalexiei commented Aug 16, 2026 •

edited

Loading

vercel Bot commented Aug 18, 2026 •

edited

Loading

marcalexiei Aug 19, 2026 •

edited

Loading