Which scope/s are relevant/related to the feature request?

create-analog

Information

Summary

When using Analog content routing with Markdown, Shiki syntax highlighting, and Mermaid diagrams, there is currently no supported way to exclude Mermaid blocks from the Shiki pipeline. In CI environments with limited memory (e.g. Cloudflare Pages), this leads to consistent out-of-memory (OOM) failures during build/SSR.

This appears to be a design/API limitation combined with incomplete documentation rather than a misuse or a runtime bug.

Context

• Analog.js content routing
• Markdown content
• Shiki enabled as syntax highlighter
• Mermaid used for diagrams in Markdown
• Build executed via vite build
• CI environment: Cloudflare Pages (~2GB heap)

Problem

To support Mermaid blocks in Markdown, the documentation suggests adding:

shikiOptions: {
  highlighter: {
    additionalLangs: ['mermaid'],
  },
}

However:

• Including mermaid in Shiki causes high memory usage and frequently results in OOM during CI builds.
• Removing mermaid from Shiki causes the build to fail with:

Language `mermaid` not found

because marked-shiki attempts to highlight all fenced code blocks, and Analog does not currently expose a way to intercept or exclude specific languages before Shiki runs.

This creates a dead-end configuration:

• Mermaid included in Shiki → OOM in CI
• Mermaid excluded from Shiki → build error
• No supported hook or API to selectively bypass Shiki for Mermaid blocks

Observations

• This is not specific to Analog alone, but Analog’s current API does not expose:
  • a way to exclude specific fenced languages from Shiki
  • a way to mark certain blocks as “raw” or “client-only”
• WithMarkdownRenderer does not support marked extensions or token filters.
• The documentation shows additionalLangs: ['mermaid'] as a valid example, but does not warn about the memory implications in constrained CI environments.
  Expected / Requested Feature

One of the following would resolve the issue cleanly:

• A supported way to exclude specific languages (e.g. mermaid) from the Shiki pipeline.
• A configuration option such as:
  • skipLanguages: ['mermaid']
  • rawLanguages: ['mermaid']
  • clientOnlyLanguages: ['mermaid']
• Or explicit documentation recommending client-side-only Mermaid rendering when using Shiki in SSR/CI environments.

Why this matters

This affects:

• Content-heavy sites (blogs, documentation)
• DevRel / educational use cases
• Cloudflare Pages and other CI environments with limited memory

Without a supported approach, users are forced to choose between:

• unstable builds
• undocumented hacks
• or removing Mermaid from Markdown entirely

Conclusion

This does not appear to be a bug, but rather a design limitation and documentation gap.
Clarifying or extending the API around Shiki + Mermaid would significantly improve the developer experience for real-world content use cases.

Happy to help further with testing or validation if needed.

Describe any alternatives/workarounds you're currently using

At the moment, the only stable workaround is to avoid using Mermaid in the Markdown + Shiki pipeline altogether.

I would be willing to submit a PR to fix this issue

• Yes
• No