🧩 Layout Inheritance

Compose complex UIs naturally with deeply nested layouts.

Crown's layout inheritance system allows you to define a layout.nim file in any directory. The framework automatically wraps the pages in that directory (and its subdirectories) with the corresponding layout.

💡 In fact, this documentation page itself is built using nested layouts! The sidebar to your left is rendered by src/app/docs/layout.nim.

How it works

When a user visits /docs/routing, Crown evaluates the directory tree from the root down to the target page, wrapping the HTML output at each level:

// 1. Root Layout (src/app/layout.nim)

// 2. Docs Layout (src/app/docs/layout.nim)

<main>

// 3. Target Page (src/app/docs/routing/page.nim)

<h1>File-System Routing</h1>

</main>

</body></html>

Creating a Layout

A layout is simply a Nim file that exports a layout* procedure. It takes a content string as a parameter and returns a string.

import crown/core

proc layout*(content: string): string =
  return html"""
    <div class="docs-layout">
      {content}
    </div>
  """

State Preservation: Because Crown uses intelligent client-side routing, navigating between pages that share the same layout will NOT re-render that layout. This means scroll position, video playback, and local UI state in the sidebar remain perfectly preserved!