> ## Documentation Index
> Fetch the complete documentation index at: https://docs.go-mizu.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Overview
> Server-side HTML templating with Go's html/template
The `view` package provides server-side HTML rendering using Go's built-in `html/template` engine. It adds a thin layer on top for layout support, custom functions, and development-friendly features like hot reloading.
## What is Server-Side Rendering?
When a user visits your website, the server generates the complete HTML page and sends it to their browser. This is called **server-side rendering (SSR)**.
```
User Request Server Browser
| | |
| GET /users | |
|--------------->| |
| | |
| | 1. Fetch data |
| | 2. Render template |
| | 3. Return HTML |
| | |
| ... | |
|<---------------| |
| | |
| | Display page |
| |------------------->|
```
**Benefits of SSR:**
* Fast initial page load (browser displays content immediately)
* SEO-friendly (search engines can read your content)
* Works without JavaScript
* Simple mental model (one language, one place)
## What the View Package Provides
| Feature | Description |
| ---------------- | --------------------------------------------------- |
| Template Engine | Wraps Go's `html/template` with convenience methods |
| Layouts | Wrap page content in a consistent structure |
| Custom Functions | Add your own template helpers |
| Hot Reload | Templates reload automatically during development |
| Embedded Files | Bundle templates in your binary for production |
## How It Works
The view package follows a simple flow:
```
Engine
┌─────────────────────────────────────────────────────────┐
| |
| Config Templates Output |
| ┌─────────┐ ┌─────────────┐ ┌─────────────┐ |
| | Dir | | pages/ | | | |
| | FS |--->| layouts/ |---->| ... | |
| | Funcs | | | | | |
| | Layout | └─────────────┘ └─────────────┘ |
| └─────────┘ |
| |
└─────────────────────────────────────────────────────────┘
```
1. **Configure** - Tell the engine where templates are and how to process them
2. **Load** - Engine parses and caches your template files
3. **Render** - Pass data to a template, get HTML back
## Directory Structure
The view package expects templates organized in subdirectories:
```
views/
├── layouts/
│ └── default.html # Layout templates
└── pages/
├── home.html # Page templates
└── about.html
```
* **layouts/** - Templates that wrap around page content (HTML shell, navigation, footer)
* **pages/** - Individual page templates that define content
## Quick Example
Here's a minimal example showing the view package in action:
**Directory structure:**
```
myapp/
├── main.go
└── views/
├── layouts/
│ └── default.html
└── pages/
└── home.html
```
**views/layouts/default.html:**
```html theme={null}
{{.Data.Title}}
{{.Content}}
```
**views/pages/home.html:**
```html theme={null}
Welcome, {{.Data.Name}}!
You have {{.Data.Count}} messages.
```
**main.go:**
```go theme={null}
package main
import (
"github.com/go-mizu/mizu"
"github.com/go-mizu/mizu/view"
)
func main() {
// Create the template engine
engine := view.New(view.Config{
Dir: "./views",
Development: true,
})
// Create the app
app := mizu.New()
// Add engine to app (makes it available in handlers)
app.Use(engine.Middleware())
// Define a route
app.Get("/", func(c *mizu.Ctx) error {
return view.Render(c, "home", view.Data{
"Title": "My App",
"Name": "Alice",
"Count": 5,
})
})
app.Listen(":8080")
}
```
When you visit `http://localhost:8080`, you'll see:
```html theme={null}
My App
Welcome, Alice!
You have 5 messages.
```
## Template Data
When you render a template, your data is wrapped in a structure that provides additional context:
```go theme={null}
// What you pass:
view.Render(c, "home", view.Data{
"Title": "My App",
"User": currentUser,
})
// What templates receive:
// .Page.Name - Template name ("home")
// .Page.Layout - Layout name ("default")
// .Data - Your data (access .Data.Title, .Data.User)
// .Content - Rendered page content (only in layouts)
```
**In page templates:**
```html theme={null}
{{.Data.Title}}
Welcome, {{.Data.User.Name}}
```
**In layout templates:**
```html theme={null}
{{.Data.Title}}
{{.Content}}
```
## When to Use View
**Use the view package when:**
* Building traditional server-rendered websites
* Creating admin dashboards
* Building email templates
* Generating any HTML from Go
**Consider alternatives when:**
* Building single-page applications (SPAs) with React/Vue/etc.
* Building APIs that return JSON
* Using a separate frontend framework
## What's Next?
1. **[Quick Start](/view/quick-start)** - Build your first page step by step
2. **[Engine](/view/engine)** - All configuration options explained
3. **[Templates](/view/templates)** - Go template syntax guide
4. **[Layouts](/view/layouts)** - Page structure and inheritance
5. **[Functions](/view/functions)** - Built-in and custom helpers
6. **[Production](/view/production)** - Deployment best practices