| <%= tx.created_at.strftime("%b %d") %> |
<%= tx.category.humanize %> |
<%= tx.formatted_amount %>
|
<%= tx.formatted_balance_after %> |
<% end %>
```
## Quick setup checklist
1. **Define your plans** in `config/initializers/usage_credits.rb`
2. **Define your operations** with their costs
3. **Uncomment the fulfillment job** in `config/recurring.yml`:
```yaml
refill_credits:
class: UsageCredits::FulfillmentJob
queue: default
schedule: every 5 minutes
```
4. **Wire up Stripe prices** to your plans
5. **Add `spend_credits_on` calls** where you want to charge credits
## Wallet-level operations
`usage_credits` is built on the [`wallets`](https://github.com/rameerez/wallets) gem, which provides the underlying ledger. This means wallet-level operations like transfers are available:
```ruby
# Transfer credits between users (refunds, gifting, etc.)
seller.credit_wallet.transfer_to(
buyer.credit_wallet,
500,
category: :refund,
metadata: { order_id: 42 }
)
```
Transfers preserve expiration buckets by default. For cash-like behavior (evergreen on receive):
```ruby
seller.credit_wallet.transfer_to(
buyer.credit_wallet,
500,
expiration_policy: :none
)
```
## Going deeper
The [`usage_credits` gem documentation](https://github.com/rameerez/usage_credits) covers:
- Dynamic pricing (`costs 10.credits + 1.credit_per(:mb)`)
- Credit expiration and rollover policies
- Upgrade/downgrade handling
- Refund behavior
- Full callback system for analytics
- Transaction audit trails
- Wallet-level transfers and expiration policies
For multi-currency wallets, game resources, or marketplace balances, see [[guides/wallets-beyond-credits|Beyond credits: wallets for games, telecom, and marketplaces]].
---
## Blog and content (CMS)
RailsFast includes a simple yet powerful file-based content management system (CMS) powered by [Sitepress](https://sitepress.cc/). This means you can easily create blog posts, legal pages, cornerstone content, and other static pages directly as files in your codebase, so it's perfect for AI agents like Claude Code to create and edit content for you.
There's no database or admin panel. You just create markdown files and they're instantly live.
> [!NOTE]
> **When to restart the server:** Content changes (editing markdown files) are hot-reloaded. However, you must restart the server (`bin/dev`) after: adding new layouts, modifying `sitepress.rb`, changing `railsfast.yml`, or adding new cornerstone pages with `footer_section`.
## Quickstart example
You can create a new blog post with a new URL by adding a `.html.md` file to `app/content/pages/blog/`. Read the sample file to understand what to put in that file and all available options. Here's a minimal example:
```markdown
---
title: My first post
---
This is a new **blog post** in my RailsFast blog.
```
Save the file as `my-first-post.html.md`. This will automatically "create" the URL `/blog/my-first-post`. That's it! Just create Markdown files and enjoy!
## How it works
Your RailsFast app content lives in `app/content/pages/`.
The directory structure maps to what URLs look like, so if you have a URL that's `blog/my-post`, you'll find that Markdown file under `app/content/pages/blog/my-post.html.md`:
```
app/content/pages/
├── blog/
│ ├── index.html.erb → /blog
│ ├── my-post.html.md → /blog/my-post
│ └── another-post.html.md → /blog/another-post
├── legal/
│ ├── terms.html.md → /legal/terms
│ └── privacy.html.md → /legal/privacy
└── software-licensing.html.md → /software-licensing (cornerstone content)
```
## Layouts
Layouts control how your content is wrapped and styled. They live in `app/content/layouts/`:
| Layout | Purpose | Auto-applied to |
|--------|---------|-----------------|
| `blog.html.erb` | Blog posts with date, author, tags, featured image | `/blog/*` posts |
| `cornerstone.html.erb` | Educational/SEO pages with CTA footer | None (specify in frontmatter) |
| `legal.html.erb` | Legal docs with navigation between terms/privacy | `/legal/*` pages |
| `listing.html.erb` | Simple wrapper for index pages | None (use explicitly) |
### Auto-applied layouts
You don't need to specify `layout:` in frontmatter for most pages. RailsFast automatically applies layouts based on the URL path:
- Blog posts under `/blog/*` get the `blog` layout
- Legal pages under `/legal/*` get the `legal` layout
This is configured in `config/initializers/sitepress.rb`.
### Cornerstone content
Cornerstone pages are foundational educational content that lives at root-level URLs (e.g., `/software-licensing`, `/how-it-works`). They're great for SEO and establishing topical authority.
```markdown
---
title: Software licensing explained
subtitle: Adding licenses to software doesn't have to be difficult.
description: Learn what software licensing is and how it works.
layout: cornerstone
image: content/hero.jpg
footer_section: learn
footer_title: Software licensing
nav_order: 1
---
Your content here...
```
Cornerstone pages include a CTA section at the bottom encouraging signups.
## Frontmatter options
Every content file starts with YAML **frontmatter** between `---` markers.
### Content visibility flags
These flags control where content appears:
| Flag | Effect |
|------|--------|
| `draft: true` | Excluded from sitemap, footer, and listings. Use for work-in-progress. |
| `example: true` | Excluded everywhere. Use for template files in the base repo. |
| `unlisted: true` | Published and accessible, but hidden from listings (blog index, footer). Still in sitemap. |
```yaml
---
title: Work in Progress
draft: true # Won't appear anywhere until you remove this
---
```
```yaml
---
title: Getting Started Template
example: true # Template file in base repo, excluded from downstream apps
---
```
```yaml
---
title: Secret Landing Page
unlisted: true # Accessible at /secret-page but not listed anywhere
---
```
### Blog posts
```yaml
---
title: Your Post Title # Required - used in 
