TeXBlox -Beautiful LaTeX math blocks for Confluence

Render beautiful LaTeX mathematical formulas directly in Confluence pages. No external dependencies, fully offline operation with bundled KaTeX. Simple macro with inline/block display modes!

Comment

Inspiration

Working in research and development, I watched brilliant colleagues struggle with a frustrating choice: document their work in Confluence where the team collaborates, or maintain separate LaTeX files where mathematics looks professional and correct. Screenshots of equations and random PDFs littered our documentation - unmaintainable and unsearchable. There had to be a better way to bridge collaborative documentation and mathematical precision.

What it does

TeXBloX brings publication-quality LaTeX rendering directly into Confluence. Users insert a macro, type their formula using standard LaTeX syntax, and get beautifully rendered mathematical notation that flows naturally with their documentation. Whether it's engineering formulas, statistical models, or physics equations, teams can now maintain both mathematical rigor and seamless collaboration without leaving their documentation platform.

How we built it

TeXBloX architecture diagram

TeXBloX is built entirely on Atlassian's Forge platform as a Confluence macro. The core rendering uses KaTeX, bundled directly into the app to meet "Runs on Atlassian" requirements with no external CDN dependencies. All typesetting happens client-side for maximum security and performance. I implemented both inline and block display modes and carefully tuned the iframe sizing to prevent layout issues.

Challenges we ran into

Iframe sizing nightmares: Confluence's macro iframe had unpredictable behavior with dynamic content. Complex expressions would get clipped or squished. I solved this with careful measurement logic, generous padding calculations, and detection for matrices and multi-line expressions.

Configuration persistence: Getting macro parameters to flow correctly through Forge's context system required trial and error across multiple configuration sources.

Manifest layout constraints: Forge macros must declare their layout (inline vs. block) statically in the manifest, preventing dynamic layout switching based on user configuration. I worked around this by creating a centering wrapper within an inline macro that mimics block-level centering behavior.

KaTeX bundle integration: Packaging KaTeX and its fonts for offline use within Forge required careful webpack configuration and asset management. The library expects CDN delivery by default, so adapting it to work entirely from bundled resources meant understanding how KaTeX loads fonts, handles CSS, and manages its rendering pipeline.

Accomplishments that we're proud of

  • "Runs on Atlassian" badge - TeXBloX is a fully self-contained application that works entirely within Atlassian infrastructure
  • Pattern matching library - Created an extensive natural language parser for common mathematical expressions
  • Published on the Atlassian marketplace - with existing users today!
  • Beautiful LaTeX output

What we learned

LaTeX in a constrained iframe environment requires obsessive attention to measurement and sizing. Every browser, every formula type, every display mode has edge cases. I learned to be generous with spacing, patient with font loading, and creative with CSS workarounds.

The "Runs on Atlassian" certification process made me think hard about the architecture of my app, especially about security and data isolation. Meeting those requirements made TeXBloX a better, more trustworthy application. I learned how to build my dependencies into my application bundle, how to test with developer tools that my app behaves the way I claim, and how to test Forge apps in a CI/CD pipeline.

What's next for TeXBlox - Beautiful LaTeX math blocks for Confluence

Expanded equation library: Pre-built templates for common formulas in physics, mathematics, statistics, and engineering with one-click insertion for frequently-used expressions. Some are currently present in the published application.

Rovo agent: Leverage Rovo to allow users to describe the formula they are looking for and have it be inserted into their page with natural language.

Chemistry support: Extend beyond mathematics to chemical formulas, reaction diagrams, and molecular structures using mhchem extensions.

Built With

Share this project:

Updates