Content files

Content files are Markdown files in the content/ directory that provide student-facing narrative for a project. They give students context about why they are doing something and what they should understand — not how to do it.

Content files are optional. A project works fine with just the inline text fields in spec.yaml. Content files become useful when you want richer formatting, longer explanations, or images that don’t fit comfortably in a YAML string.

File types and mapping

Each content file corresponds to a specific field in spec.yaml. When a content file exists, it takes precedence over the spec field — the file wins.

Spec field	Content file path	Purpose
`overview`	`content/overview.md`	Project introduction shown before the student begins
`recap`	`content/recap.md`	Completion summary shown after the student finishes
`objective.description`	`content/{objective_id}.md`	Narrative for a specific objective
`step.instructions`	`content/{objective_id}_{step_id}.md`	Context for a specific step

For example, if your project has objective 01 and step 02, the step content file lives at content/01_02.md.

What each file type covers

content/overview.md introduces the project before the student begins. Set the scene and motivate the work — what problem does this project solve, why does this technology matter, what will the student have built by the end. Leave prerequisites and learning outcomes in spec.yaml where they belong.

content/recap.md is shown after the student completes the project. Reinforce what they accomplished, what concepts they should now understand, and how this connects to real-world practice.

content/{objective_id}.md explains why this objective matters before the student starts it. Provide conceptual grounding — what is the student trying to achieve at a high level, what pattern does this objective illustrate. Leave step-by-step instructions and solution hints out of this file.

content/{objective_id}_{step_id}.md provides background for a specific step. Explain the concept the student needs to understand to complete the step meaningfully — what is this resource or configuration, why does it exist, what would happen without it.

Resolution rule

When both a content file and a spec field exist for the same scope, the content file wins. This means you can start with short inline text in spec.yaml and promote to a richer content file later without changing the spec.

The typical lifecycle looks like this:

Write a short description directly in spec.yaml — enough to capture the intent
When you want richer formatting, longer narrative, or images, create the corresponding content file
The preview server and hints generator automatically pick up the content file from that point on

There’s no need to remove the spec field when you create a content file. The spec field serves as a fallback and a summary; the content file provides the full version.

Callouts

Content files support four callout types. Use them sparingly — one or two per file at most. Overuse dilutes their impact.

:::NOTE
Supplementary context that enriches understanding but is not critical to completing the step.
:::

:::TIP
Practical advice that helps the student work more effectively or avoid common confusion.
:::

:::WARNING
A common pitfall or mistake that students frequently make at this point.
:::

:::IMPORTANT
A critical prerequisite or constraint the student must understand before proceeding.
:::

Here’s what each one looks like when rendered:

Content file type	Starlight admonition	Use for
`:::NOTE`	`:::note`	Supplementary context — interesting but not blocking
`:::TIP`	`:::tip`	Practical advice — helps the student work smarter
`:::WARNING`	`:::caution`	Common pitfalls — things students frequently get wrong
`:::IMPORTANT`	`:::danger`	Critical prerequisites — must be understood before proceeding

Code examples

Illustrative examples are welcome. Prescriptive content is not.

Allowed — teaches the concept without giving the answer:

The bucket name must be globally unique across all AWS accounts. A common pattern
is to append a random suffix:

    my-project-a3f9c2b1

The exact name doesn't matter — what matters is that it's unique and follows
S3 naming rules (lowercase, no underscores, 3–63 characters).

Not allowed — gives the answer away:

Run this command to create the bucket:

    aws s3api create-bucket --bucket my-project-a3f9c2b1 --region us-east-1

Then enable website hosting:

    aws s3 website s3://my-project-a3f9c2b1/ --index-document index.html

The distinction: illustrative examples show the shape of a solution or a general pattern. Prescriptive content gives the exact commands, parameter values, or step-by-step walkthrough that removes the learning challenge. The hints generator handles the “how” — content files handle the “what” and “why”.

Images

Place images in the images/ directory at the project root and reference them with a relative path from the content file:

![VPC architecture diagram](../images/vpc-overview.png)

Use images to illustrate architecture, data flow, or concepts. Avoid console screenshots that show the solution steps — those give the answer away.

The SDK’s validate_project tool reports a BROKEN_IMAGE_REFERENCE warning if a content file references an image that doesn’t exist in images/, and an UNREFERENCED_IMAGE warning for image files that aren’t referenced by any content file.

Framing and source material

If you have source material — a blog post, architecture diagram, existing lab, or narrative scenario — it can enrich the content files without affecting the technical pipeline.

Source material is optional. If you have it, use it to:

Enrich the narrative voice and give students real-world context
Reference the original source with a link so students can explore further
Adapt the scenario for the student audience without reproducing it verbatim

Source material should never change the objectives, instructions, or solution code. It lives in the content layer only.

Content files and the authoring workflow

Content generation is author-directed. You can write content files manually, ask Kiro to generate them, or skip them entirely for a given scope. A project without any content files is perfectly valid — the spec fields provide the student-facing text.

The preview server renders content files as part of the navigable HTML view of your project. See Preview server for how to launch it and what it shows.