Writing a new entry
On this page
This page covers writing a new entry with Ghostwriter, from choosing what to write to putting the draft into the entry. To change an entry that already exists, see Editing an existing entry.
Starting
Open a section's new entry screen and click Write with Ghostwriter at the top. Or click Write with Ghostwriter beside New entry on the entry index, while a section Ghostwriter writes for is chosen: it starts a new entry with Ghostwriter open. The button shows in the sections Ghostwriter writes for, for people with the Use Ghostwriter permission (see Permissions).
On an existing entry, the button is Edit with Ghostwriter. See Editing an existing entry.
You can also start from Ghostwriter's own screens: Write beside a section on the Overview, Write something on the widget, the last step of Get started, or Draft this on an idea in the content plan. Each opens a new entry with Ghostwriter already open.
Ghostwriter opens in a large panel over the entry. The entry stays where it is underneath.
What are you writing?
Choose what this entry is:

- From the content plan, shown first: ideas on the content plan for this section. Ghostwriter fills in the brief from the idea's title and notes straight away, without asking first.
- A kind you taught it, such as "Case study". It asks that kind's own questions, and models the entry on that kind's examples. See Kinds of content.
- Something like what is already here: groups of entries built the same way (the same Matrix or Neo blocks), found from the section's own entries, such as "3 entries built the same way". Choosing one starts the general brief, modelled on those entries. Shown only for sections whose entries come in more than one shape.
- Something else: a general brief for anything. Tick up to six entries under Model it on in the brief, or leave them all unticked to let Ghostwriter choose the shape.
Teach a kind, beside the heading, teaches one for this section (see Teaching a kind yourself).
Below these, Or carry on with lists the pieces in this section whose entry isn't saved yet, with "Started by …" and "last changed by …". With shared conversations on (the default) that's everyone's pieces; otherwise only yours.
The brief
Once you've chosen, the conversation opens and Ghostwriter asks for the quick details in one message: "What’s it called, and what should it say? A line or two is plenty." Answer in the box below it: a working title and a line or two is enough. Press ⌘↵ (or Ctrl+↵) or click Send.

Without a voice guide, a notice says Ghostwriter will still write, but in a plain voice rather than yours.
Ghostwriter then fills in the whole brief for that kind of content from your answer ("Filling in the brief…", one model call), and shows it in the conversation as the brief card:
- Working title.
- Every one of the kind's questions, with its answer.
- Model it on, with the entries it will follow ticked: the kind's own examples, when it has them; otherwise up to six live entries Ghostwriter chose as closest in purpose and shape to the new piece, best first. Tick or untick up to six; Try again keeps what's ticked.
Anything only you can know, such as a figure, a quote or a client's name, is left in [square brackets] for you, and the card says so. Ghostwriter never makes up facts about your organisation: a figure or quote you didn't give is replaced with [Add: the figure] or [Add: the quote].
Change any answer in the card, then:
- Looks right, start writing keeps the brief on the piece and starts the writing. Anything still in square brackets is fine: Ghostwriter asks about it, or leaves the gap marked in the draft. A required question can't be left empty.
- Try again fills in the brief again from what you said. The answers you changed are kept exactly as you wrote them; the rest are answered afresh.

Draft this on an idea in the content plan skips the question: the brief card arrives already filled in from the idea, ready to check.
Once agreed, the card folds away to Show the brief. Open it to read or change the brief at any time and click Save the brief: nothing is rewritten straight away, and Ghostwriter works from the changed brief from your next message. It can't be changed while Ghostwriter is working.
The card is a labelled region, and screen readers hear "The brief is filled in. Check it, then start writing." when it arrives. Press ⌘↵ (or Ctrl+↵) in the card to agree to it (or to save it, once agreed).
Ghostwriter uses only facts from the brief and the conversation. It doesn't invent figures, quotes or client names. Where it needs something it doesn't have, it asks, or leaves a
[note in square brackets]for you.
The conversation
After Looks right, start writing, the conversation carries on. While Ghostwriter works, a line says what it's probably doing ("Reading the brief…", "Thinking it through…", "Writing. Long drafts take a while…"; "Revising the draft…" for a change).
If Ghostwriter needs facts only you know before it can write, it asks first: four short questions at most, headed Ghostwriter needs your answer and announced to screen readers. Each question has its own box, labelled with the question, with a hint under it when one helps; a question with a few set answers has radio buttons instead, and one it can do without is marked (optional). Skip a question you can't answer: Ghostwriter writes around it or marks the place for you to fill in. Add anything else opens a box for anything more. Send answers (or ⌘↵ / Ctrl+↵ in any box) sends them all as one message; Just draft it with what you have has it write now and mark the gaps in [square brackets]. Once sent, the questions stay in the conversation with your answers under them.

Ghostwriter's replies are shown with their formatting: lists, bold and links.
Once there is a draft, ask for changes in plain words:
- "Make the opening shorter."
- "Add a section on cost, after the process."
- "Less formal."
Press ⌘↵ (or Ctrl+↵) to send, or click Send. A draft usually takes a minute or two. Show the brief opens the brief card again (see The brief).
Each draft adds a line to the conversation, such as "Draft written · 294 words" or "Draft updated · 270 → 279 words (+9)".
If a turn fails (the provider was busy, say), the panel says That didn’t work with the reason, and Try again sends the same message again. If filling in the brief fails, Try again fills it in again. See Troubleshooting.
The draft
The draft sits on the right, in three tabs:
- Preview (the default once there's a draft) shows it as the page it would make, rendered by the section's own template. See Preview.
- Blocks lays it out the way the entry is built: its fields, and its Matrix or Neo blocks in order.
- Text shows just the words.
The arrow keys move between the tabs. In Blocks and Text:
- In Text, gaps show as chips (facts to add, counts to check, links to choose), as in the Preview, and a chip opens the same box to deal with it. Writing with a chip in it starts editing when you click its words, or Tab to it and press Enter (or start typing): then you see it exactly as it's kept, raw markers and all, and that is what's saved.
- Change any writing where it's shown. The draft says "Click any writing (or Tab to it) to change it. It’s saved when you leave it; Esc puts it back." Click it, or press Tab to reach it, and type. It's saved when you leave it. Esc puts it back as it was, and Enter finishes a one-line piece such as a heading.
- Edit YAML opens the whole draft as text, to add, move or remove blocks. Most people never need it.
While Ghostwriter is working, the draft can't be changed, since what it writes would replace the change.
In a narrow window (a tablet or a phone), the conversation and the draft take turns: Conversation and Draft at the top switch between them. A dot on Draft means the draft has changed since you looked; a dot on Conversation means Ghostwriter is working, or (amber) waiting for your answer. The box for your message stays at the bottom of the conversation.
The word count is shown at the top. A block type the section doesn't allow is flagged, and left out when the draft is used. A block with nothing to write says "Uses its usual settings."

Preview
Preview renders the draft through the section's own page template, as Craft's own preview does, so you see the page as it would look. "Rendered with the site’s own templates. Hover to see the blocks. Nothing is saved until you use the draft." The frame's bar reads Preview · not saved.

-
Nothing is saved. Ghostwriter builds exactly what Use this draft would put in, and renders it without saving any draft, entry or nested entry. Image fields show what Use this draft would put there: an image you've chosen, a stock photo's preview (to editors, as in Live Preview), or the striped placeholder once Ghostwriter has made one in that volume.
-
Hover to see the blocks. Each block of the page builder, each section of rich text and each top-level field is outlined with its name as the pointer moves over it ("Where to put one · in Body"). The outlines follow the page as it resizes and loads.
-
One scrollbar. The page is shown whole, as tall as it is: the draft's column scrolls through the layouts and the page together, with no second scrollbar inside the page. A full-screen hero is shown as tall as the panel.
-
Desktop / Phone switches the width: the panel's width, or 390 px. On a phone, Desktop shows the page laid out at 1280 px, scaled to fit.
-
After a change (a new draft, a change in the conversation, or writing changed in Blocks or Text), the preview renders again once the changes stop. "Updating preview…" shows in the bar while it does, and the last version stays in view.
-
Gaps show as what they are, not as raw text. A fact only you know (
[[ask: adult ticket price]]in the draft) is an amber chip reading "adult ticket price", titled "Only you know this: add it before publishing". A count to check shows its number ("3 areas") with a dotted amber underline, titled "Counted from '…'. Check it before publishing". A link still to choose has a dashed amber underline, titled "Link to choose". Screen readers hear "Fact to add:", "Count to check:" and "(link to choose)". The layout cards' thumbnails show them too. Until you deal with them, the draft keeps the markers, and so does the entry once you use it, so Finish this page finds them.
-
Click a chip (or Tab to it and press Enter) to deal with it here, in the draft, before you use it. A small box opens at the chip:
- a fact to add: "Only you know this: adult ticket price", with a box for your answer, Add it and Leave it for later. Your answer goes into the draft exactly as you type it: no model is asked, and nothing is reworded;
- a count to check: "Counted from ‘Northumberland, Durham and the Tyne Valley’. 3 areas, is that right?", with Looks right, Change it and Remove it;
- a link to choose: the page Ghostwriter suggested for it first, then the pages its hint suggests ("Link to About"), or Choose an entry to find one by its title. A link in the writing points at the page's address, and so does a button's Link field.
The preview, the layouts, Blocks and Text follow at once, and in a shared conversation everyone sees the change. A gap dealt with here is gone from the draft, so Finish this page won't ask about it after Use this draft; one you leave for later still shows there. Esc closes the box and puts you back on the chip.
-
Links in the preview do nothing, so you stay on the draft. Forms can't be sent from it.
-
Edits of an existing entry are previewed the same way: the entry with the changes, unsaved.
When there's no page to show, the tab says why and offers Show blocks instead:
- the section has no URLs, or no template, for this site;
- the template couldn't render the draft ("The page template couldn’t render this draft: …"; admins also see the error and the template);
- the page took more than 8 seconds (with a page already showing, it stays: "This page is slow to render; showing the last version").
Turn the tab off with preview in configuration.
For template authors
A preview is a normal page request with a token, so your templates run as they do in Craft's Live Preview. craft.app.request.isPreview is true for any preview, and ghostwriterPreview is true only for Ghostwriter's:
{# Analytics and embeds: not in any preview #}
{% if not craft.app.request.isPreview %}
<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXX"></script>
{% endif %}
{# Something only for Ghostwriter's preview #}
{% if ghostwriterPreview ?? false %}…{% endif %}
Even without that, third-party scripts (tag managers, analytics, chat widgets) and their requests are blocked in the preview; your site's own scripts run. If your templates load scripts from a CDN, allow it with previewScriptHosts. The page is shown in a frame on the control panel's own domain, so a server that sends X-Frame-Options: DENY for every page stops the preview, as it stops Live Preview. CKEditor nested entries render through their entry type's partial template (_partials/entry/<type handle>.twig); one with no partial shows as a plain box with its text.
Comments
Comment on the page itself and let Ghostwriter revise just those parts. Turn on Comment in the draft's toolbar (or press Alt+Shift+C). The count on the button is your comments not sent yet, plus those sent and not resolved.
- Pin a comment: click a block, or select some words in one, and write what should change in the small box that opens there. ⌘↵ (Ctrl+Enter) adds it; Esc cancels. Each comment gets a numbered pin on its block, or at the words.
- Your comments are yours until you apply them. They stay in this browser, even if you reload or close the panel. Click a pin, or use Edit and Delete in the list under the page, to change one. Comment on the whole page adds one about the page as a whole.
- Apply N comments sends them together, as one message in the conversation ("2 comments", each with its block and words; click one to see it on the page). Ghostwriter makes one call, in the queue, and changes only the commented blocks. The layout stays unless a comment asks for a new one.
- Ghostwriter answers with one message, with a reply to each comment:
- Changed: the block changed, and the page shows it with a green Changed mark. Before / after shows the change word by word, and Put it back undoes it.
- Replied: an answer with no change.
- Not applied: a check refused the change, and the reply says why. A fact you give in a comment may fill a gap, and is labelled as yours.
- Skipped: someone changed that block while Ghostwriter worked. Apply again to use the new version.
- Resolve a comment when you're done with it: its pin goes. Reopen brings it back.
- Comments follow their words when you switch layout. If a layout leaves a comment's words out, it says "Not in this layout".
- Shared conversations: comments that have been sent are in the conversation, so everyone on the piece sees them. While the comments are open, the panel checks for new ones every 10 seconds.
- Keyboard: in comment mode, Tab into the page lands on its first block. The arrow keys move between blocks, Enter opens the box, and Alt+Shift+M comments on words you've selected. The list under the page has every action, including Show on page.
Adding, editing, resolving and putting back cost nothing. Only Apply asks the model, once, however many comments it carries (up to 12).
Layouts
The first draft comes laid out more than one way: the same words arranged differently, the writer's own layout first (As written), then up to two others. They're in the Layout row above the draft, as a row of names with the chosen one marked, so the Preview has the room. Beside each name, a few words say what it changes against As written: "Quote moved up", "Call to action added", "Text split into 3 blocks · A section moved down". Suggested marks the one most like your existing pages; it means "like your pages", not "best".
- Compare layouts shows them as cards, each with a small live picture of the page it makes (rendered with your templates, like the Preview), its name, a line on what it does and how many blocks it has. Hide thumbnails puts the row back. Your choice is remembered in this browser.
- Choose a layout and the Preview, Blocks and Text show it, and the button reads Use this draft (Quote up top). The choice is kept on the piece, so everyone working on it sees the same one. Choosing costs nothing: no model call.
- Switching points at the change. Once the new layout shows, the draft's column scrolls to the first block it changes, and every changed block is outlined for about two seconds, in the Preview and in Blocks and Text. With reduced motion, the column jumps there and the outline is still, then gone. Only switching does this, never opening a piece.
- The words are the same in every layout. A layout only moves them between blocks, splits or joins them, and may place an extra (below). It never writes words of its own. Change writing where it's shown, as usual, and every layout follows. In a layout other than As written, words the layout put together from several places in the draft are shown but not edited there ("Put together for this layout…"): change them in As written, or ask in the conversation.
- While the other layouts are found (one more model call, after the draft), the draft already shows, and the row says "Finding other layouts…".
- After you change the draft, the other layouts follow it. One that no longer fits says Needs refreshing and can't be chosen; Refresh layouts asks again (one model call).
- Only layouts that look noticeably different are offered. One that only sets a line as a quote, or turns a list into paragraphs, near the foot of the page is dropped before you see it, and so is one too like another on offer.
- The row is hidden when there's only one layout: an entry that's being edited, a page with too little to arrange, when no other layout came back, or when none looked different enough. The button is then plain Use this draft. Nothing is shown as an error.
- Keyboard and phones. The layouts are buttons: Tab reaches them, ← and → move between them, Enter or Space chooses. On a phone the cards scroll sideways.
Under the draft's toolbar, the layouts, the draft and the Preview scroll as one column: the page is shown whole, as tall as it is, so there's one scrollbar, not one for the panel and another for the page.
There's no setting: this is how drafting works. A first draft is four model calls: the writer, two for links to your other pages and its search title and description, and the layout planner. Later changes are one, and one more when they rewrite enough of the page for the search title and description to follow.
Extras
With the first draft, the writer also prepares extras where your section has a block for them: numbers, a pull quote, questions and answers, an "at a glance" box, captions, a second call to action, a testimonial, a short intro. A layout uses them where it has room; one that no layout uses never reaches the entry.
They're at the foot of the Text tab: "Prepared with the draft, only from what you told me, the draft itself or your existing pages."
- Each extra says whether the chosen layout uses it (Used in Sections apart), and each item where it came from: from your brief, from your answer · question 2, from the draft, from one of your pages (linked), or your words once you've changed it.
- Nothing is made up. An item whose facts aren't in what you gave Ghostwriter is dropped. One waiting on a fact only you know says Needs your answer.
- A count it worked out ("3 counties" from "Northumberland, Durham and Cumbria") is counted by Ghostwriter, not the model, and says Counted from your brief: “…” and Needs review. It's a step in Finish this page before the page can go live.
- A fact to add or a count to check shows as a chip, as in the Preview, and clicking the chip opens the same box to answer or check it there. Click the words around it (or Tab to them and press Enter) to change them, and you'll see them as they're kept, markers included (
[[ask: years trading]]). - Click an item to change it. It's saved when you leave it. Enter finishes, and Esc puts it back as it was.
- ✕ deletes an extra (or one item of it). A layout that used it is arranged again without it.

Headings
Ghostwriter fits every draft's headings to the page, with no setting:
- The body starts below the page's main heading. Most templates print the entry's title as the H1, so a draft's sections start at H2. The Preview tab reads which headings the template prints each time it renders a draft, and keeps that per section and entry type; if your template prints the H1 from another field, or none, later drafts follow it once two previews agree.
- Only the levels a CKEditor field offers. A field whose toolbar offers H2 and H3 never gets an H4: a deeper heading becomes a bold lead-in ("Heading. Its paragraph"). A field without the Heading button gets no headings.
- No skipped levels, no empty headings, and a bold line used as a heading becomes a real one. Words are never changed.
A template that prints no H1, a logo as the H1, or more than one, is noted at the top of Ghostwriter's plugin settings. Ghostwriter still starts the text at H2; the fix belongs in the template.
Links to your other pages
A first draft comes with a few links to your other pages, where they help the reader: about one for every 250 words, two to five in all, counting links the draft has already. Ghostwriter picks the words and the pages, checks in code that each page is real and can be linked to, then a second call reads each link in its paragraph and keeps it only if it reads naturally. So a first draft is two more calls; later changes add none.
- What it can link to. Every live page on the site that has an address: entries in any section with URLs (singles too), and categories with pages of their own and at least 40 words of their own text. Not pages that are disabled, not yet live or expired, set to noindex (in SEOmatic, or by a
noindexlightswitch), the home page, pages such as search, login or checkout, or the page itself. Key pages such as Contact or About can be offered whatever the draft is about. - While it looks, the draft pane says "Draft ready. Checking headings and links…". You can read the draft, but Use this draft, Edit YAML and changing the writing wait until it's done. The other layouts are found meanwhile, and every layout carries the same links.
- It says what it did. A line under the first draft names the pages: "I linked to 2 of your pages: Winter structure: plants that earn their keep in January, Contact." If nothing was close enough: "I didn't find pages close enough to link to."
- The links it added are marked in the Text and Blocks tabs with a dotted underline and a small mark. Hover over one, click it or put the caret in it to see where it goes: the page's title and type, its address and why it was chosen, with Open page and Remove link. Removing a link keeps the words, and it isn't put back by a later change. The marks are only in the panel; nothing about them is saved.
- The writer's own links to a real, live page of the site (one it could link to, above) are kept as it wrote them. A link it couldn't place stays a link to choose, and Ghostwriter suggests the page it most likely means, checked by the second call: Finish this page and the chip's box offer that page first ("Link to Contact"), for you to choose. It's never put in for you. Links to choose don't count towards the two to five.
- Later changes keep to real pages. If you ask for a change and the writer adds a link to an address it wasn't given, it becomes a link to choose instead, so a made-up address never reaches the entry.

After Use this draft, each link it added is a suggestion in Finish this page, so someone checks where it goes. In the entry, a link is kept as Craft's own reference to the entry ({entry:12@1:url}), so it follows the page if its address changes.
Search
The same call that looks for links also writes how the page may show in search results, and Ghostwriter makes its address. They're in the Search section at the foot of the Text tab, below the extras: "How this page may appear in search results. Nothing here is saved until you use the draft."
- Meta description. One or two plain sentences, only from what the page says, about 120 to 155 characters for SEOmatic's usual 160 (a Plain Text field's own character limit counts instead). The count beside it ("149 / 160") turns amber outside that range; its tooltip says the range.
- SEO title. Most pages keep using the page title, which is what SEOmatic does by default: the row says "Uses the page title: “…”" in grey, and why. Ghostwriter only writes one when the page title is too long once the site's name is added. Give it its own lets you write one; Use the page title goes back.
- Address. On a new entry, the slug is made from the title, keeping the whole phrase, as people search for it: "What to do in the garden in March" becomes
what-to-do-in-the-garden-in-march. Only a long title (over about 60 characters) loses its little words ("the", "for", "in") and is cut to six words. A leading "the" or a trailing "for" comes off either way, a year stays only in a channel (a journal, news), and the slug is apart from the section's other entries. On a published entry it's shown greyed: "Published pages keep their address". - Click any of them to change it. It's saved when you leave it (Enter finishes, Esc puts it back), and it's yours from then on: a later change to the draft won't rewrite it. Otherwise, if you ask for a change that rewrites the title or a quarter of the words, the title and description are written again (one call).
- Try again asks for another title and description ("Asks for another title and description. Uses Ghostwriter."): one call, "Writing another…" meanwhile.
The fields it fills are SEOmatic's SEO Settings field (its title and description) and Plain Text fields with the handles seoTitle, metaTitle, seoDescription or metaDescription. It never writes over a person's text. On Use this draft:
- an empty description, or one Ghostwriter wrote before and nobody has changed, gets the draft's;
- a description someone wrote stays. The Search section says "Your SEO description stays. Suggested instead: …", with Use this to put the draft's in after all;
- one SEOmatic takes from another field (the section's Excerpt, say) is left when it fits, and suggested over when that field is empty or too long or short;
- a Twig template, or a setting switched off, is left alone.
In SEOmatic, the text goes in with the field's Override switch on and its source set to custom text, as you would set them by hand; with the switch off, SEOmatic would ignore it. The slug is set only on an entry that has never been published, whose slug is still empty or the one Craft made from its title, and only where the section's URI format uses {slug}; Craft keeps it unique when it saves.
Use this draft
Use this draft puts the draft into the entry, then reloads the form so you can see it.
- The chosen layout goes in (see Layouts), with any extras it uses. With As written chosen, it's the draft as written.
- Nothing is saved or published. It goes into the entry's own Craft draft. Check it over, then save the entry as usual, or discard it.
- The search title, description and address go in too, where Ghostwriter may write them: never over a person's text, and the slug on a new entry only.
- A new entry starts unpublished. Its Enabled switch is turned off, so you can save it straight away, and an AI draft is never published by accident. The notification says "Ghostwriter drafts start unpublished. Switch on Enabled when you're ready." Switch it on when the entry is ready. An existing entry's status is never changed. Turn this off with New entries start unpublished in the settings (
draftsUnpublished). - Using it again replaces what is in the form.
- Opening the panel again carries on with the same piece, with a line saying it's already in the entry.
A notification says "Draft added to the form. Check it over, then save." If there's anything still for you to do, it lists it, and stays until you close it. For example:
- Still to choose by hand: related entries, categories, dates, images.
- Still to set by hand, as it differs from page to page: links the house style couldn't settle, marked "(link still to choose)".
- Ghostwriter drafts start unpublished. Switch on Enabled when you're ready.
A striped placeholder marks each image still to pick, where the section's entries usually have a picture, and Finish this page opens by itself to take you through it and anything else left.

Carrying on later
The conversation is saved as you go. Close the panel and open it again on the same entry, and it carries on with the last piece you were on, including after a page reload. Coming back later, choose it under Or carry on with, click it under In progress on the Overview, or click Resume on its idea in the content plan.
Start over goes back to What are you writing? to begin a new piece. The earlier piece isn't deleted; it is still offered under Or carry on with, and stays on the Overview until it's removed.
A piece leaves In progress once its entry is saved. A draft put into the entry and left unsaved is still listed, as "In the entry, not saved".
Sharing conversations
Conversations are shared with everyone who may use Ghostwriter, so a colleague can pick a piece up where you left it, brief card and all. Each message shows who sent it, and Or carry on with says who started each piece and who last changed it. See Shared conversations.