site

Example site

A minimal Docusaurus 3 site that demonstrates @ebuildy/docusaurus-plugin-gitlab and serves as the fixture for the package's end-to-end test.

It consumes the package from the repo root via file:../.., so it always builds against your local dist/ (run pnpm run build at the root first).

The doc pages reference a placeholder project, group/repo, which only resolves under the e2e stub server. To run this as a real demo, point the components at projects that actually exist (see Running standalone).

Layout

examples/site/
├─ docusaurus.config.ts   # registers the remark plugin + plugin options
├─ sidebars.ts            # autogenerated sidebar from docs/
├─ src/theme/
│  └─ MDXComponents.ts     # makes <Gitlab*> components available in every .mdx
└─ docs/
   ├─ intro.mdx            # homepage (slug: /) with live embeds
   └─ components/          # one documentation page per component
      ├─ _category_.json
      ├─ project-info.mdx
      ├─ readme.mdx
      ├─ releases.mdx
      ├─ issues.mdx
      └─ file.mdx

How the plugin is wired in

Two integration points — the same two any consumer needs:

docusaurus.config.ts ──► presets.classic.docs.remarkPlugins:
                           [ remarkGitlab, { host, token, strict } ]
                         (runs at build time; fetches + injects data props)

src/theme/MDXComponents.ts ──► { ...MDXComponents, ...Gitlab }
                         (registers <GitlabProjectInfo>, <GitlabReadme>,
                          <GitlabReleases>, <GitlabIssues>, <GitlabFile>
                          so .mdx pages can use them without imports)

Plugin options used here

Option	Value	Notes
host	process.env.GITLAB_HOST ?? "https://gitlab.com"	Overridden to the stub URL by the e2e test.
token	process.env.GITLAB_TOKEN	Empty in the e2e (stub needs no auth).
strict	true	A failed fetch aborts the build (so the e2e catches regressions).

Required configuration (and why)

These settings are what make the build succeed; don't remove them:

Setting	Where	Why
No "type": "module"	package.json	With it, Docusaurus's CommonJS server bundle loads as ESM and SSG fails with require.resolveWeak is not a function.
slug: /	docs/intro.mdx frontmatter	Renders the index doc to build/index.html.
onBrokenLinks: "ignore"	docusaurus.config.ts	The site is a fixture/demo, not a link-checked doc set.
routeBasePath: "/"	docusaurus.config.ts	Serves docs at the site root.

Running

As the e2e fixture (recommended)

You normally don't run this site directly — the e2e test drives it against a mocked GitLab API. From the repo root:

pnpm run build                      # build the plugin into dist/
pnpm exec vitest run test/e2e/build.test.ts

See test/README.md for how that test works.

Running standalone

To build or preview the site yourself, first make sure the plugin is built and the components point at real projects:

# from the repo root (pnpm install covers the whole workspace, examples included)
pnpm install       # first time only
pnpm run build

# from examples/site
export GITLAB_HOST=https://gitlab.com
export GITLAB_TOKEN=glpat-xxxxxxxx  # required for private projects

pnpm run build     # production build  → ./build
pnpm run serve     # serve the production build locally
# or
pnpm start         # dev server with hot reload (http://localhost:3000)

Available scripts: build, start, serve, clear.

Because the bundled pages use the placeholder group/repo (which doesn't exist on gitlab.com) and strict: true is set, a standalone build will fail until you edit the project="..." props in docs/ to real, reachable projects.

Adding a page

Drop a new .mdx file in docs/ and use any component, e.g.:

<GitlabFile project="your-group/your-repo" path="README.md" />

The autogenerated sidebar picks it up automatically.