docs: fix broken GitHub code-reference blocks after fumadocs migration (#12213)

# Which Problems Are Solved

Pages in `apps/docs` that embed source from GitHub via the Docusaurus
convention

````
```js reference

https://github.com/zitadel/actions/blob/main/examples/org_metadata_claim.js
```
````

stopped working after the migration from Docusaurus to fumadocs. The old
`docusaurus-theme-github-codeblock` plugin used to fetch the file and
render it; fumadocs has no support for that meta, so the page rendered
the raw URL as plain code-block text. Visible at
`/docs/apis/actions/code-examples` and 16 other pages.

# How the Problems Are Solved

- Converted every ```` ```<lang> reference\n<URL>\n``` ```` block (46
total across 17 `.mdx` files) to the native fumadocs JSX form:
`<GithubCodeBlock url="<URL>" />`. The existing `<details>`/`<summary>`
collapsibles around blocks are kept — they're an authoring choice, not
part of the rendering bug.
- Updated `apps/docs/components/github-code-block.tsx` to render via
`DynamicCodeBlock` from `fumadocs-ui/components/dynamic-codeblock`
(proper shiki highlighting) instead of raw `CodeBlock` + `Pre` (which
produced unhighlighted output). Also fixed language detection so a URL
hash like `#L10-L20` no longer pollutes the language token.
- Registered `GithubCodeBlock` globally in
`apps/docs/mdx-components.tsx`, matching how every other shared
component (`APIPage`, `Callout`, `Tab/Tabs`, `Step/Steps`, `Admonition`,
`TerminologyUpdate`) is exposed. MDX files no longer need a local
`import`.

# Additional Changes

- Normalized the two MDX files that were already using the JSX form
(`examples/secure-api/python-django.mdx`,
`examples/secure-api/java-spring.mdx`): removed their now-redundant
local `import { GithubCodeBlock }` and rewrote 9 long-form
`<GithubCodeBlock url="..."></GithubCodeBlock>` tags to self-closing for
consistency.

# Additional Context

Verified locally with `pnpm --filter @zitadel/docs dev`:

- `/docs/apis/actions/code-examples` — 20 shiki-highlighted code blocks
rendered inside the `<details>` collapsibles (was 0).
- `/docs/apis/openidoauth/claims` — line-range hashes (`#L9-L11`)
honored.
- `/docs/examples/login/flutter` — mixed languages (xml/dart/html)
detected and highlighted.
- `/docs/guides/integrate/external-audit-log` — edge case of fenced
reference indented inside a numbered list also converted and rendered.

Greps:
- `^[ \t]*\`\`\`[a-zA-Z0-9]+ reference` in `apps/docs/content/**/*.mdx`
→ 0 matches.
- `<GithubCodeBlock url="` in `apps/docs/content/**/*.mdx` → 55 matches.
- `from '@/components/github-code-block'` in
`apps/docs/content/**/*.mdx` → 0 matches.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]>
This commit is contained in:
Florian Forster
2026-05-28 11:02:44 -07:00
committed by GitHub
co-authored by Claude Opus 4.7
parent c73e58489b
commit f4f43f5248
21 changed files with 103 additions and 186 deletions
@@ -3,7 +3,6 @@ title: Secure Java Spring Boot API Application with ZITADEL
description: "Secure Java Spring Boot APIs using OAuth 2.0 Token Introspection with ZITADEL."
sidebar_label: Java Spring Boot
---
import { GithubCodeBlock } from '@/components/github-code-block';
This integration guide shows you how to integrate **ZITADEL** into your Java Spring Boot API. It demonstrates how to secure your API using
OAuth 2 Token Introspection.
@@ -45,7 +44,7 @@ into Spring Security `authiorities`, which can be used later on to determine the
So in your application, create a `support/zitadel` package and in there the `CustomAuthorityOpaqueTokenIntrospector.java`:
<GithubCodeBlock url="https://github.com/zitadel/zitadel-java/blob/main/api/src/main/java/demo/app/support/zitadel/CustomAuthorityOpaqueTokenIntrospector.java"></GithubCodeBlock>
<GithubCodeBlock url="https://github.com/zitadel/zitadel-java/blob/main/api/src/main/java/demo/app/support/zitadel/CustomAuthorityOpaqueTokenIntrospector.java" />
### Application server settings
@@ -55,11 +54,11 @@ In a new `config` package, create the `WebSecurityConfig.java`.
This class will take care of the authorization by require the calls on `/api/tasks` to be authorized. Any other endpoint will be public by default.
It will also use the just created CustomAuthorityOpaqueTokenIntrospector for the introspection call:
<GithubCodeBlock url="https://github.com/zitadel/zitadel-java/blob/main/api/src/main/java/demo/app/config/WebSecurityConfig.java"></GithubCodeBlock>
<GithubCodeBlock url="https://github.com/zitadel/zitadel-java/blob/main/api/src/main/java/demo/app/config/WebSecurityConfig.java" />
For the authorization (and the server in general) to work, the application needs some settings, so please provide the following to your `application.yml` (resources folder):
<GithubCodeBlock url="https://github.com/zitadel/zitadel-java/blob/main/api/src/main/resources/application.yml"></GithubCodeBlock>
<GithubCodeBlock url="https://github.com/zitadel/zitadel-java/blob/main/api/src/main/resources/application.yml" />
Note that the `introspection-uri`, `client-id` and `client-secret` are only placeholders. You can either change them in here using the values provided by ZITADEL
or pass them later on as arguments when starting the application.
@@ -75,7 +74,7 @@ If authorization is required, the token must not be expired and the API has to b
For tests we will use a Personal Access Token or the [Java Spring web example](../login/java-spring).
<GithubCodeBlock url="https://github.com/zitadel/zitadel-java/blob/main/api/src/main/java/demo/app/api/ExampleController.java"></GithubCodeBlock>
<GithubCodeBlock url="https://github.com/zitadel/zitadel-java/blob/main/api/src/main/java/demo/app/api/ExampleController.java" />
## Test API