# Getting started: build a blog with Rustango-CMS
This walkthrough takes you from an empty directory to a working blog with an editor's admin: a page tree, two page types, a Markdown body stored in its own database table, and public pages served from templates you own. No database server to install — everything here runs on SQLite.
> **Time:** about 20 minutes, most of it waiting for the first compile.
>
> **Runnable version:** every step below produces the project in [`examples/cms_demo`](../examples/cms_demo). If something looks off, diff against it.
---
## What you need first
| Rust 1.88+ | Compiler | <https://rustup.rs> |
| The scaffolder, `rcms` | Generates a new site project | `cargo install rcms-scaffold` |
`cargo install` downloads only the scaffolder, a small program that builds in seconds; you install it once. The generated project gets `rustango-cms` and the `rustango` framework from crates.io.
Check what you have:
```bash
rustc --version # should print 1.88 or newer
rcms --version # the scaffolder; its version is the Rustango-CMS release it creates
```
---
## Step 1: Generate the project
The scaffolder is `rcms`: it generates a new site project.
```bash
rcms new myblog --dir ~/projects --template blog
```
`--template blog` gives you a home page plus an article type with a real Markdown body. (The other option, `--template minimal`, gives you the same two page types with no typed fields — useful when you want to design your own from scratch.)
> **Want a finished-looking site instead?** `--theme blog`, `--theme news`, `--theme portfolio` or `--theme blog-portfolio` creates a complete site with pages, menus and colours, and no Rust models. See [Starter themes](themes.md). This guide builds a site by hand so you see how each piece works.
It prints exactly what to run next:
```
Created Rustango-CMS project `myblog` (blog template) at /Users/you/projects/myblog
Next:
cd /Users/you/projects/myblog
cargo run -- makemigrations # emits cms_article_page
cargo run -- quickstart
```
Every command in this guide is the same in bash, zsh and Windows PowerShell. The project carries its database location in a `.env` file and builds for SQLite by default, so there is nothing to export and no flags to pass.
> **On Windows** use `$HOME` instead of `~` in paths: `--dir $HOME\projects`. PowerShell does not always expand `~`, and you would get a folder literally named `~`.
Here's what it wrote:
```
myblog/
├── Cargo.toml # depends on rustango-cms + rustango
├── .env # DATABASE_URL for the local SQLite database
├── .env.example # every setting, documented
├── .gitignore
├── README.md # the same commands, kept for later
├── migrations/ # written on the first run: the CMS migrations, then yours
├── src/
│ ├── main.rs # wires the admin + public router together
│ ├── models.rs # your page types
│ └── quickstart.rs # the one-command local setup
└── templates/
├── _site.css.html # starter styles, included by both templates
├── home_page.html
└── article_page.html
```
Two files are yours to change; the rest you can mostly ignore at first. `src/models.rs` defines what kinds of page exist, and `templates/` decides how they look.
---
## Step 2: Generate your own migration
Everything from here runs inside the project:
```bash
cd ~/projects/myblog
```
The two page types in `src/models.rs` are yours, not the CMS's, so their tables aren't in the shipped migrations. `ArticlePage` stores its body in a table called `cms_article_page`, and this writes the migration that creates it:
```bash
cargo run -- makemigrations
```
The first build takes a few minutes. Later commands reuse it.
```
no changes for registry scope
wrote migrations/0017_create_cms_article_page.json (tenant scope)
+ CreateTable("cms_article_page")
+ CreateIndex { name: "cms_article_page_page_id_idx", ... }
```
Never write those JSON files by hand: `makemigrations` compares your models against the last snapshot and writes the difference. Run it again any time you change a model, followed by `cargo run -- migrate-tenants` to apply it.
---
## Step 3: Create the site and start it
```bash
cargo run -- quickstart
```
It asks for a password for the `admin` user (at least 12 characters), then starts the server. On the first run it does three things before that:
1. **Creates the registry.** rustango-cms is multi-tenant: one registry database knows about your sites, and each site gets its own storage. Even a single-site blog goes through this, so you can add a second site later without restructuring anything.
2. **Creates the site `demo`** in its own SQLite file, `var/demo.db`, reached at the hostname `demo.localhost`. This applies every migration, including the one from Step 2.
3. **Creates the user `admin`**, so you can sign in.
Run it again later and it skips what already exists and just starts the server; `cargo run -- runserver` does the same. To do these steps by hand (another site name, another host), see the project's README.
> **Email from forms** needs one more setting. Add a long random `RUSTANGO_SECRET_KEY=...` line to `.env`: it encrypts the secrets the site stores, such as notification tokens. Keep it the same between restarts.
Leave it running and open <http://demo.localhost:8080/login>. The hostname matters: it's how the server knows which site you're asking for. `demo.localhost` resolves to your own machine without any `/etc/hosts` editing.

Sign in as `admin` with the password you chose. You land on the dashboard:

Everything is empty, which is right — you haven't made anything yet.
---
## Step 4: Create the home page
Click **Pages** in the sidebar.

Choose **Create the first page**. The CMS asks which type of page you want:

Only two types are offered, and "Article" isn't one of them. That's `src/models.rs` talking:
```rust
#[async_trait]
impl PageTypeHandler for ArticlePage {
fn allowed_parent_types(&self) -> &'static [&'static str] {
&["HomePage"]
}
// …
}
```
An article can only live under a home page, so the CMS won't offer it at the top of the tree. You get to state rules like that once and have the admin enforce them everywhere.
Pick **Home page**, title it `My Blog`, and set **Status** to `Published`. The slug fills itself in from the title.

Click **Create page**.
> The slug is what appears in the URL, so this page will be served at `/my-blog`. Clear the slug entirely if you want a page at the site root instead — the help text under the field says so, but the auto-fill will have put something there already.
---
## Step 5: Write an article
Open **My Blog**, then **Add the first child**. This time the type picker looks different:

Only **Article** is offered — the same rule as before, seen from the other side. The banner spells out why: options are filtered by both the parent's `allowed_child_types` and the candidate's `allowed_parent_types`.
Pick **Article**, title it `Hello, world`, set **Status** to `Published`, and this time use **Create & keep editing** so you stay on the page.
Now the editor shows something the home page didn't: a **Body (Markdown)** field with a formatting toolbar, and a **Hero image** picker. Those come from `ArticlePage`'s typed extension table — they're real columns, declared in `src/models.rs`:
```rust
#[derive(Model, Debug, Clone, Serialize, Deserialize)]
#[rustango(table = "cms_article_page", app = "site")]
pub struct ArticleBody {
#[rustango(primary_key)]
pub id: Auto<i64>,
#[rustango(fk = "cms_page", on = "id", index, unique)]
pub page_id: i64,
#[rustango(max_length = 16000)]
pub body_markdown: String,
#[rustango(fk = "cms_media", on = "id")]
pub hero_media_id: Option<i64>,
}
```
Type some Markdown into the body and press **Save & keep editing**. The preview pane on the right updates:

> The new-page form shows these fields too, so you can fill in the body before the first save. This step used **Create & keep editing** so you stay in the editor and see the preview.
---
## Step 6: Look at the site
Open <http://demo.localhost:8080/my-blog>:

The article is listed because `templates/home_page.html` loops over `children`, which the CMS puts in the context for every page:
```html
{% for child in children %}
<li><a href="{{ url_prefix }}/{{ child.slug }}">{{ child.title }}</a></li>
{% endfor %}
```
Follow the link:

That's `templates/article_page.html`, and it's short enough to read in full:
```html
<article>
<h1>{{ page.title }}</h1>
{% if extension.hero_media_id %}
<img src="{{ rcms_image_url(media_id=extension.hero_media_id, filter='fill-1200x600') }}"
alt="{{ page.title }}">
{% endif %}
{{ extension.body_markdown | markdown | safe }}
</article>
```
`extension` is the typed row you saw in the editor. `| markdown` turns it into HTML; `| safe` is required after it, because the filter has already sanitized its output and Tera would otherwise escape the tags and show them as text.
---
## How it fits together
Three ideas carry most of the CMS:
**The page tree is the site.** Every page has a parent, and the URL is built from the slugs along the path. Moving a page in the admin moves its URL, and the children come with it.
**A page type is a Rust struct plus a handler.** The handler says what the type is called, which template renders it, and where in the tree it's allowed to sit. The CMS reads those answers and builds the admin around them — the type picker, the field list, the validation.
**Typed fields live in their own table.** Shared things — title, slug, status, publication dates — are columns on `cms_page`. Fields specific to one type go in a table you own, joined by `page_id`. Your article bodies are queryable columns, not JSON in a blob.
Everything an editor sees is generated from those three. You didn't write a form, a list view, or a URL route to get here.
---
## Where to go next
- Change `templates/_site.css.html` — it's plain CSS inlined into both page templates, with nothing else depending on it.
- Add a third page type: copy the `HomePage` block in `src/models.rs`, add a force-link line in `src/main.rs`, and run `makemigrations` if it has typed fields.
- Switch to PostgreSQL when you're ready to deploy. The generated `README.md` has the same sequence without the SQLite-specific flags, and [Run Rustango-CMS in production](production.md) covers secrets, migrations, the reverse proxy, media and caching.