What is tilt.mdx?

tilt.mdx is a special kind of text file that mixes regular Markdown (the simple language used for writing docs) with JSX code (a way to write interactive UI components). The “tilt” part just tells you that the file belongs to the Tilt project, and the “.mdx” extension means it can contain both Markdown and JSX.

Let's break it down

  • Markdown part: You write headings, paragraphs, lists, links, and images just like in any .md file.
  • JSX part: Inside the same file you can drop small pieces of React‑style code, such as <Button> or <CodeExample>, which will turn into live, interactive elements when the page is built.
  • Front‑matter: At the very top you can add a block of YAML between three dashes (---) to set metadata like the page title or sidebar order.
  • Build step: When the Tilt website is generated, a tool called MDX compiles the file, turning the Markdown into HTML and the JSX into real React components.

Why does it matter?

Because it lets developers write documentation that is both easy to read and able to show live examples. Instead of linking to a separate demo, you can embed a working piece of code right inside the doc, making learning faster and reducing the chance of outdated screenshots.

Where is it used?

tilt.mdx files are used throughout the official Tilt documentation site. Any open‑source project that builds its docs with the MDX framework can also adopt the same format, so you’ll see it in blogs, tutorial sites, and internal knowledge bases that need interactive content.

Good things about it

  • Keeps docs and code examples together, so they stay in sync.
  • Allows reuse of UI components (buttons, alerts, code blocks) across many pages.
  • Works with static‑site generators, giving fast page loads while still supporting interactivity.
  • Markdown syntax stays simple for non‑programmers, while JSX adds power for those who need it.

Not-so-good things

  • You need a build pipeline (Node, MDX, React) to turn the file into a web page, which adds setup complexity.
  • Beginners who only know Markdown may be confused by the JSX sections and have to learn a bit of React.
  • Debugging errors can be harder because problems might come from either the Markdown or the embedded JSX.
  • Overusing JSX can make the file look cluttered, reducing the readability that plain Markdown provides.