A frontmatter block that fits your static site, built once per project

If your blog lives in a git repo, the top of every post file matters. That --- block tells Jekyll, Hugo, Astro or your Next.js code what the post is called, when it goes out and how to render it. If it's wrong, the build breaks or the post turns up with no title.

In RankMill you set that block once per project. From then on, every post in that project gets the same frontmatter shape. Here is how to set it up so a downloaded file drops into your repo with no hand edits.

What the frontmatter list is

Each project has an ordered list of frontmatter fields. Each field becomes one line in the --- block at the top of the file, in the order you put it in the list.

A few things to know:

• The list holds up to twenty fields.
• A new project starts with two: the title and the publish date.
• You can add fields, remove them, or clear the list completely.
• The setting belongs to the project, so two projects can have very different blocks.

Every field in the list is one of three kinds. Picking the right kind for each field does most of the work.

The three field kinds

Filled by RankMill

RankMill already knows two things about every post: its title and its publish date. Fields of this kind take their value from the post itself. You don't type anything, and no agent guesses.

Use these for the fields your site can't build a page without. Almost every setup wants a title. Most want a date too.

Fixed to a literal

A fixed field has the same value on every post in the project. You type it once and it's done. Good examples:

• layout: post for a Jekyll theme
• a fixed author, when one person signs every post
• draft: false for Hugo, so posts aren't left out of production builds

These are the lines you'd otherwise paste into every file by hand. That chore is exactly what this setting removes.

Written by the agent

The third kind is filled by the agent, from a description you give it. You say what the field is for, and it writes a value for each post.

Good candidates are fields that change from post to post and need some judgement:

• description, a short summary for search results and link previews
• excerpt, a teaser for your blog index page
• category, one label picked for the post

The description you write is the agent's only guide, so make it specific. "Description" on its own tells it very little. "One sentence that sums up the post for someone deciding whether to click" tells it plenty. If a field should only take certain values, say so and list them.

One rule of thumb: if the value should be the same on every post, it's a fixed field, not an agent field.

Example shapes for common generators

These are the usual conventions. Your theme or your code may expect something different. The best reference you have is a post that already works on your site. Open it, look at its frontmatter, and rebuild that block field by field.

Jekyll

A typical Jekyll post uses these fields:

• layout: fixed, set to post (or whatever your theme calls its post layout)
• title: filled by RankMill
• date: filled by RankMill
• categories: written by the agent, if your theme uses them

Jekyll posts in _posts also carry the date in the file name. Keep that in mind when you save a downloaded file into that folder.

Hugo

Hugo reads a --- block as YAML. A simple setup looks like this:

• title: filled by RankMill
• date: filled by RankMill
• draft: fixed, set to false
• description: written by the agent, if your theme shows it

The draft line matters. Hugo leaves drafts out of a normal production build, so being explicit saves you a confused afternoon.

Astro

Astro content collections check frontmatter against a schema you define. If a required field is missing, or has the wrong name, the build stops with an error.

That makes Astro the strictest of the four, and also the easiest to get right. Your schema is a written list of what each post needs. Match your RankMill list to it key for key. Common fields are a title, a description and a publish date. Any optional field in the schema can stay out of your list.

Next.js

Next.js has no built-in frontmatter convention. Your own code reads the block, often with a small library such as gray-matter. So the answer is in your repo, not in a guide.

Find the place where your code reads post files. Note every frontmatter key it uses. Put exactly those keys in your list, and nothing else.

Making the most of twenty fields

Twenty is a ceiling, not a target. Most sites need far fewer. A long block is harder to check, and every agent field is one more thing to review before a post goes out.

A few habits that help:

• Only list what your site reads. A field nothing uses is noise in every file.
• Prefer fixed over agent. If a value never changes, don't ask the agent to write it.
• Keep agent fields few and clear. One or two well-described fields beat six vague ones.
• Mind the order. The block comes out in list order. If your team likes a certain order, set it once here.

When an empty list is the right answer

An empty list is a real setting. It means no frontmatter at all. The file starts with the post's # heading.

That's the right choice when:

• Your site doesn't use frontmatter. Some Next.js setups take the title from the first heading, or keep post details in a separate file.
• You paste posts into another tool. If you copy a post into an editor that has its own title and date fields, a --- block is just clutter to delete.
• Something else adds the block. If a script or build step in your repo writes the frontmatter, let it do that job alone.

Don't keep the default two fields "just in case". A renderer that doesn't expect frontmatter may show the block as a horizontal line followed by a line of text at the top of your post.

How this fits with publishing to GitHub

If your project is connected to a repository through the RankMill GitHub App, finished posts go out as pull requests. RankMill works out where your repo keeps its posts and writes the file there.

The frontmatter list decides what the top of that file looks like. So a block that matches your site is what turns a pull request into something you can merge without edits. It's worth getting right before your first publish.

A quick setup checklist

Here's the whole thing in order:

1. Open a post that already works on your site and copy its frontmatter somewhere you can see it.
2. For each line, decide the kind. Title and date are filled by RankMill. Anything identical on every post is fixed. Anything that needs judgement per post is written by the agent.
3. Build the list in the same order as your example.
4. Write a clear description for each agent field.
5. If your site doesn't read frontmatter, clear the list instead.
6. Download one finished post, drop it into your repo, and run your build locally.

That last step is the real test. If the page builds and looks right, you're done for this project. Every post after that arrives in the same shape.