Feat/gitlab group page generation

README.md

@@ -264,6 +264,77 @@ Both components render [scoped labels/topics](https://docs.gitlab.com/ee/user/pr
 (`scope::value`, e.g. `Abilities::Performance`) as a two-part badge — the scope keeps its
 color and the value gets a dark-gray background. The split is on the last `::`.
 
+## Generating pages from a group
+
+Instead of writing one page per project by hand, drop a single directive on a
+**folder's index page** and let the plugin generate a child page per project in
+a GitLab group at build time. The generated pages become **children of the
+declaring page** in the sidebar.
+
+Put the directive on the folder's index doc — `index.mdx`, `README.mdx`, or a
+doc named after its folder (Docusaurus's [category index
+convention](https://docusaurus.io/docs/sidebar/autogenerated#category-index-convention)):
+
+```mdx
+---
+title: Group projects
+---
+# docs/team/index.mdx
+
+# Our GitLab projects
+
+{@generateGitlabPages group="my-group" sections="info,readme" includeSubgroups=false}
+```
+
+| Attribute | Type | Default | Description |
+|---|---|---|---|
+| `group` | string \| number | — | **Required.** Group path or ID |
+| `sections` | string | `"readme"` | Comma-separated list of `info`, `readme`, `releases`, `issues` — becomes the components rendered on each generated project page |
+| `topics` | string | — | Comma-separated topic filter; only projects with **all** listed topics are included |
+| `includeSubgroups` | boolean | `false` | Include projects from subgroups |
+| `includeArchived` | boolean | `false` | Include archived projects |
+
+The plugin writes one `<project-slug>.mdx` per project **as a sibling of the
+declaring page** (subgroups become nested folders with their own
+`_category_.json`), so the autogenerated sidebar nests them under the declaring
+page:
+
+```text
+docs/team/
+  index.mdx        <- the declaring page (parent)
+  acme-web.mdx     <- generated child
+  acme-api.mdx     <- generated child
+  frontend/        <- generated subgroup
+    _category_.json
+    web-app.mdx
+```
+
+Generated files are **git-ignored** (the plugin writes a scoped `.gitignore` in
+the folder that ignores only what it generated — never your index page) and are
+regenerated on every build, tracked via a `.gitlab-generated` manifest so stale
+pages are removed on regeneration. Never hand-edit or commit them. Generation
+runs once at plugin init, before the docs plugin scans the filesystem, so the
+generated pages feed the autogenerated sidebar like any other doc. Keep the
+declaring page's folder dedicated to this generation.
+
+You can also (re)generate the pages without a full build:
+
+```bash
+npx docusaurus gitlab:generate
+```
+
+> During `docusaurus start`, generation runs once per process at startup.
+> Editing the `{@generateGitlabPages …}` attributes (group, sections, topics,
+> …) requires restarting `docusaurus start` to regenerate — it is not
+> re-evaluated on hot reload.
+
+On the declaring page itself, the directive is replaced with a
+`<GitlabProjectGrid>` card grid — one card per project, linking to its generated
+child page. Because the declaring page is a folder index, it is served at a
+directory URL with a trailing slash (e.g. `/team/`), so each card links to the
+child with a bare relative slug (`<slug>` → `/team/<slug>`). If your site sets
+`trailingSlash: false`, adjust routing accordingly.
+
 ### `::include` directives inside included markdown
 
 When a fetched GitLab README or markdown file contains a GitLab