Before the AI writes anything, it reads. The reference system is how you control what it reads.
References are the source material and direction you supply to an idea card before running a pipeline. They shape what the AI knows — and what it's been told to do — before it produces a single sentence. Without them, the AI draws on its general training knowledge, which is broad but impersonal. With them, it works from your sources, your context, and your explicit instructions.
Every idea card has its own reference set. References are per idea, not global. And they're optional — if you don't add any, the pipeline still runs, it just works from whatever the AI already knows about the topic.
The Four Reference Types
Not all references work the same way. There are four types, and they serve different purposes.
Web URLs
When you add a URL, Riterly fetches the page and strips it down to plain text — navigation, ads, sidebars, and other page furniture are removed. What remains is the actual text content of the page, which becomes part of the research digest (more on that below).
This is useful when you want the AI to work from a specific article, documentation page, product page, or any publicly accessible web content rather than its general knowledge of the topic.
Uploaded Files
You can upload files directly as references. Accepted formats are PDF, markdown (.md), plain text (.txt), and code files. The content is extracted and treated the same way as fetched web content — it goes into the research digest as source material.
This covers situations where your source material isn't on the web: internal documents, exported notes, research papers, code samples you want the AI to reference.
Markdown Briefs
A markdown brief is not source material. This is the distinction most users get wrong.
A URL or uploaded file tells the AI what the topic is about. A markdown brief tells the AI what you want it to do. It's direction — your instructions, your constraints, your goals for this specific piece of content.
The brief is covered in its own section below because it's the most consequential reference type to understand correctly.
Internal Draft References
You can reference other drafts inside your Riterly account. What content gets loaded depends on where that draft is in the pipeline:
- Pending — title and notes only
- Outline Review — title, notes, and outline
- Drafted or Published — title and full draft content
This lets you build on existing work — maintaining consistency with a previous post, referencing an outline you've already approved, or pulling in a completed piece as context for something new.
One firm constraint: internal draft references are account-scoped. You can only reference your own drafts. Cross-user references are not possible.
The Markdown Brief: Direction, Not Source Material
The markdown brief is the most direct lever you have over draft quality, and the most commonly misunderstood reference type.
When users first encounter it, the instinct is to treat it like any other uploaded file — more content for the AI to read. But a brief doesn't supply information about the topic. It supplies your intent. It tells the AI what problem you're solving, what ground to cover, what to avoid, and what the output should accomplish.
A well-structured brief looks like this:
## Objective
What this piece needs to accomplish.
## The Problem I'm Addressing
The specific situation or pain point this content is responding to.
## Key Points to Cover
- Point one
- Point two
- Point three
## Tone Check
What the tone should feel like — and what it shouldn't.
## What Not to Do
Specific things to exclude or avoid in this draft.
## CTA
What the reader should do or think after reading.
The sections don't have to be exhaustive. A brief with a clear objective, two or three key points, and a specific "what not to do" will produce noticeably different output than running the pipeline with no brief at all.
You can use a brief alongside the idea card's notes field — they serve different purposes. Notes are for quick direction: a few lines to orient the pipeline. The brief is for detailed direction: everything you'd want to communicate if you were briefing a writer before they started. Both can be active at the same time.
How the Research Digest Works
When the pipeline runs, Riterly doesn't pass your raw references directly to the AI. It processes them first into something called the research digest.
The digest is a plain-English summary of the topic, followed by a bullet list of specifics — key facts, data points, version numbers, function names, gotchas, anything concrete that came out of the reference material. It's structured to give the AI a dense, usable summary of what it should know before it starts writing.
Two things about the digest matter practically:
It's cached per idea. The digest is generated once and reused. During a single pipeline run, references are never fetched twice — the same digest feeds into both Pass 1 and Pass 2. This means you don't pay a processing cost every time the AI needs to consult your sources mid-run.
It's cleared when the post is published or archived. Once a piece moves out of the active pipeline, the cached digest is cleared. If you re-run the pipeline on a draft later, references will be reprocessed.
Limitations and Important Notes
A few boundaries worth knowing before you build out a large reference set.
The context window has a ceiling. There's no hard limit on how many references you can add to an idea card, but the AI operates within a finite context window. If your combined reference material is very large, the digest may summarize rather than fully incorporate everything. For most use cases this isn't a problem — but if you're adding ten lengthy PDFs and three long articles, expect some compression.
Internal references are strictly account-scoped. There's no mechanism for referencing another user's drafts. If content from another account needs to be referenced, export it and upload it as a file.
The brief doesn't replace the notes field — they work together. Quick directional notes belong in the notes field on the idea card. Detailed instructions belong in a markdown brief uploaded as a reference. Using both is fine and often the right call.
For detail on how the research digest feeds into Pass 1 and Pass 2 of the pipeline — what happens to it, when it's used, and how it shapes each generation step — see the pipeline documentation.