feat(core): add doc resource reference type for custom documentation pages

[boyney123]

What This PR Does

Adds a new [[doc|path/to/doc]] wiki-link syntax for referencing custom documentation pages inline within MDX content. This allows authors to create rich inline links to custom docs pages with tooltips, similar to how events, services, and other resources are referenced. Also extracts badge styling into a shared utility and fixes theming to use CSS variables throughout the custom docs sidebar.

Changes Overview

Key Changes

• New doc resource type — ResourceRef.astro now handles type === 'doc' by looking up entries in the customPages collection and rendering a tooltip with title and summary
• Remark plugin update — resource-ref.ts regex updated to support forward-slash paths in the target (e.g. [[doc|guides/event-storming/02-facilitation]]), replacing the stricter [\w-]+ pattern
• normalizeCustomDocPath helper — strips URL prefixes and normalizes paths to match customPages collection IDs
• Badge styles utility — new badge-styles.ts extracts repeated badge className logic from NestedItem.tsx and CustomDocsNav/index.tsx into a single shared function with CSS variable-based theming
• Theming fixes — index.astro and VerticalSideBarLayout.astro migrated from hardcoded Tailwind colors / dark: variants to --ec-* CSS variables
• Tests — new test file resource-ref.spec.ts covering the remark plugin for doc paths, @-versioned paths, and versioned service refs
• Example catalog — updated guide and runbook MDX files to demonstrate the new [[doc|...]] syntax

How It Works

The [[doc|path/to/doc]] syntax is parsed by the remark plugin which emits a resourceRef MDX component call with type="doc". ResourceRef.astro detects this type, fetches the matching customPages entry by normalizing the path (stripping docs/custom/ prefixes), and renders an inline link with a hover tooltip showing the page title and summary. If the doc is not found, it renders a broken-link styled fallback.

Breaking Changes

None

Additional Notes

• The regex change in resource-ref.ts is intentionally permissive for path characters — callers should ensure only valid paths are passed
• The doc type intentionally bypasses resourceToCollectionMap since custom pages use a separate lookup pattern

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: 37bda63

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@eventcatalog/core	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 37bda63593

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Preserve custom badge text color

This helper now collapses badge styling to a single color derived from backgroundColor, so textColor is effectively ignored for custom doc badges. Any docs that intentionally set contrasting backgroundColor and textColor values will now render with the theme-mapped text color instead of the configured one, which can make badges unreadable or visually incorrect in production docs.

Useful? React with 👍 / 👎.