Build a website by pasting JSON
Create a website or replace a page by pasting JSON or HTML, from ready-made sections to a page designed entirely in your own code.
A JSON document describes a website's page; Magpie builds it. Each part of
the page is a section. Magpie writes the markup for a hero, text or
list section in the starter design, and an html section is your own
markup, styles and script, placed as written. A page can mix the two, or be
one html section designed from top to bottom. The document can also change
the design every page shares: its colours and font, whether it has the
header with the navigation and the footer, and styles, head tags and a
script of its own. It is for an editor website (see Build and publish a website).
There are two ways in:
- New website on the Websites page: choose Build it in the editor, open
Import from JSON, paste the document and choose Create website. A
name typed in Name is the website's name; leave it empty to use the
document's
title, which gets a number added when the team already has a website with that name. The address is the document'sslugwhen it has one, and is otherwise made from the name. - In the editor of a website you already have, choose Import JSON… in
More, paste, and choose Replace with the page's name. The paste replaces every
section of the open page. The layout every page shares (its head, styles,
header and footer) changes only where the document says so, unless the
document asks to replace the whole design with
"replace": "design".
Use Copy the prompt in either import box to get this format plus the instructions an assistant needs, then describe the business or project and paste back what it gives you. The prompt asks the assistant to find out what the website is for, how it should look and what it should say before it writes anything.
In the editor you choose what the prompt includes:
- Change what I have: the prompt ends with the whole website as one file, the layout and every page, as Code mode has it. Tell the assistant what to change, and it sends the file back with that changed and the rest kept; see Your website as one file.
- Start fresh: the prompt has only this format. The assistant starts from nothing and makes something new.
The line under the choice says what the prompt includes, and the message after copying says which one was copied. A new website has nothing to include yet, so its prompt always starts fresh.
A website file pasted into the box replaces the whole website in Code mode,
where Save page changes applies what it says about the pages. A JSON
document or a page of HTML replaces the open page, as below. A page of HTML
with <!-- magpie:page --> and <!-- /magpie:page --> in it, from an older
prompt, keeps the sections between them on this page and the rest in the
design every page shares.
Importing in the editor changes the draft. The new page replaces the open
page's draft, and visitors will see it once you publish. Undo in the
message after the import puts the page and the layout back. To go back to what
visitors see, choose Discard unpublished changes in More. The title and
the address are not changed by an import into an existing site, so slug is
ignored there and title is used only in the imported sections.
An imported website is not published. Choose Preview in the editor to open the draft in a tab of its own, as visitors will see it once it is published, then Publish when it is ready.
The whole document is checked before anything is saved. If any part of it does not fit the format below, no website is created and the problem is reported with the exact field that caused it.
Designing the page your own way
Nothing in the format holds a page to the starter design:
- No navigation bar or footer.
"header": falsetakes away the header every page shares, with the website's name and its pages."footer": falsetakes away the shared footer."header": trueputs the starter design's header back. - Your own styles for the whole site.
cssis a stylesheet for every page, placed after the design's own, so its rules win. Give any section aclassand style it there. - Fonts and other head tags.
headholds tags for the page's<head>, such as a<link>to a font.theme.fontsets the font the design uses. - A script for every page.
scriptis JavaScript that runs on every page. - Any part, or all of it, in your own code. An
htmlsection has no padding or styles of its own, so it can run edge to edge. Onehtmlsection can be the whole page, orhtmlsections can sit betweenhero,textandlistsections.
Importing again replaces the css, head and script an earlier import
added, rather than adding a second copy. A field you leave out keeps what the
website has; an empty value ("css": "") takes the earlier one out.
The text of hero, text and list sections can be edited by clicking it in
Visual mode. An html section is selected, moved and removed in Visual mode
as a whole, and its code is changed in Code mode.
Pasting a page of HTML
You can paste a page of HTML in place of JSON, such as a game an assistant wrote as one HTML file. Paste the page itself or the assistant's whole answer; Magpie takes the HTML from its code block.
- On New website, a whole page (one with
<html>or<body>) becomes the website exactly as written. The website's name is the one typed in Name; left empty, it comes from the page's<title>, or its first<h1>when it has no title, with a number added when another of the team's websites has it. A page with neither and no typed name is refused. The address is made from the name, with a number added when that address is in use. Change either in Edit details. A piece of a page, such as markup and a script with no<html>or<body>, goes into the starter design as onehtmlsection. - In the editor, the page replaces the open page's sections as one
htmlsection, inside the website's header and footer. Its styles and scripts are kept. Its title and meta tags are left out, because the website has its own. To use a whole page as the website's design exactly as written, put it in a document with"replace": "design"(see "Replacing the whole design" below).
Scripts run in Preview and on the published website, not in the editor.
The editor's preview shows the page without running its scripts, so anything
a script draws, such as a game, is blank there; open Preview to see it.
At an address that starts magpie.diy/site/, scripts do not run in Preview or
on the published website: they run at a domain of the team's (see
Build and publish a website).
The document
{
"title": "Ridgeway Cycles",
"slug": "ridgeway-cycles",
"theme": { "background": "#f5f1e8", "text": "#1d1d1b", "accent": "#b74232", "font": "Georgia, serif" },
"header": true,
"footer": true,
"head": "<link rel=\"stylesheet\" href=\"https://fonts.googleapis.com/css2?family=Fraunces&display=swap\">",
"css": ".dark { background: #1d1d1b; color: #f5f1e8; }",
"nav": [],
"sections": []
}
| Field | Type | Notes |
|---|---|---|
replace |
"page" or "design", optional |
"design" replaces the design every page shares as well as this page; see below. Left out, it is "page". |
title |
string, required | Up to 150 characters. Also the browser tab title and the website's name in the header. |
slug |
string, optional | The public address, 3 to 80 lowercase letters, numbers and hyphens. Some addresses are reserved. Left out, it is made from the title, with a number added when that address is in use. |
theme |
object, optional | background, text and accent, each a hex colour such as #b74232, and font, a CSS font list such as Georgia, serif (letters, numbers, spaces, commas, hyphens and single quotes). Any you leave out keep the design's. |
header |
true or false, optional | false takes away the header every page shares, with the website's name and its pages. true puts the starter design's header back. Left out, the header stays as it is. |
footer |
true or false, optional | false takes away the footer every page shares. Left out, it stays as it is; a footer section replaces it. |
head |
string, optional | Tags for every page's <head>, such as a font's <link>, placed as written. |
css |
string, optional | A stylesheet for every page, after the design's own. Write the rules only, without a <style> tag. |
script |
string, optional | JavaScript for every page, run at the end of the page. Write the code only, without a <script> tag. |
nav |
array, optional | Up to 20 links, shown at the top of the hero. Each is { "label": "...", "href": "#about" }. The header lists the website's pages. |
sections |
array, required | At least one section, up to 200, in the order they appear down the page. |
Replacing the whole design
"replace": "design" is for a new look for the whole website, or a page
designed from scratch with none of the website's current design. Use it only
when that is what was asked for; when it is not clear, ask. Without it, an
import changes the open page, and the shared design only where the document
says so.
- When its only section is an
htmlsection holding a whole page of HTML (with<html>or<body>), that page becomes the design and the page, exactly as written: its head, styles and scripts included. - Otherwise the document starts again from the starter design, with its
theme,header,footer,head,cssandscriptapplied.
Every page of the website shows the new design. Undo in the message after the import puts the previous design back.
{
"title": "Night Market",
"replace": "design",
"sections": [
{ "type": "html", "html": "<!doctype html><html><head><style>body { margin: 0; background: #111; color: #f5f5f5; font-family: system-ui, sans-serif; } .hero { min-height: 100vh; display: grid; place-items: center; }</style></head><body><div class=\"hero\"><h1>Night Market</h1></div></body></html>" }
]
}
Links
A href is one of these:
- an anchor on this page:
#followed by lowercase letters, numbers and hyphens, such as#visit; - another page of the website:
magpie:page/and the page's address, such asmagpie:page/about, ormagpie:page/for the home page; - a full address starting
http://orhttps://; - a
mailto:ortel:link, such asmailto:hello@example.comortel:+441422000000.
Nothing else is accepted.
Sections
Every section names a type and supplies the fields that type uses. type
defaults to text.
type |
Use it for | Required | Also takes |
|---|---|---|---|
hero |
The opening band at the top | heading |
id, class, eyebrow, lede, button |
text |
A band of paragraphs | paragraphs |
id, class, eyebrow, heading |
list |
A band of bullet points | items |
id, class, eyebrow, heading |
html |
Anything in your own markup: a designed band, a whole page, a game, a quiz, a calculator, an embed | html |
id, class |
footer |
The closing band | text |
none |
| Field | Type | Notes |
|---|---|---|
eyebrow |
string | The small line above a heading, up to 60 characters. |
heading |
string | Up to 150 characters. |
lede |
string | The larger opening line in a hero, up to 500 characters. |
button |
object | { "label": "...", "href": "#about" }, on a hero only. |
paragraphs |
array of strings | Up to 100, each up to 2,000 characters. |
items |
array of strings | Up to 200, each up to 500 characters. |
html |
string | The section's markup, with any <style> and <script> it needs, placed in the page as written. A whole HTML page is accepted too: its styles, scripts and the inside of its <body> are used. |
id |
string | An anchor for this section, so a link can point at it. Lowercase letters, numbers and hyphens, starting with a letter. |
class |
string | Class names added to the section, for css to style: letters, numbers, hyphens and underscores, separated by spaces. |
text |
string | The footer line, up to 500 characters. |
Give a section an id whenever a nav link or a hero button points at it.
Writing code for the website
The page is one document with the website's layout around it, so a few things keep code working:
- Styles for the whole site go in
css. Styles that belong to onehtmlsection can sit in that section's own<style>. Start those rules with a class of the section's own (.space-rocks canvas), because a rule forbody,htmlor*changes every page. - To design the whole page yourself, use
"header": false,"footer": false, one or morehtmlsections andcss. The starter design's stylesheet still styles plain elements such as headings and paragraphs, andcsscomes after it, so its rules win. For a page with nothing of the starter design, put a whole page of HTML in the onlyhtmlsection of a document with"replace": "design", or paste the page on New website. - A script finds its elements by a class or
idof its own. A script or stylesheet from another site needs its fullhttps://address. - Write the code as a JSON string: a double quote as
\", a backslash as\\and a line break as\n.
A complete example
{
"title": "Ridgeway Cycles",
"slug": "ridgeway-cycles",
"theme": { "background": "#f5f1e8", "text": "#1d1d1b", "accent": "#b74232" },
"nav": [
{ "label": "What we do", "href": "#services" },
{ "label": "Visit", "href": "#visit" }
],
"sections": [
{
"type": "hero",
"eyebrow": "Since 1994",
"heading": "Ridgeway Cycles",
"lede": "Repairs, wheel building and second-hand bikes in Hebden Bridge.",
"button": { "label": "What we do", "href": "#services" }
},
{
"type": "list",
"id": "services",
"eyebrow": "Services",
"heading": "What we do",
"items": ["Full service, back within 48 hours", "Hand-built wheels", "Bike fitting", "Second-hand bikes, checked and guaranteed"]
},
{
"type": "text",
"id": "visit",
"eyebrow": "Visit",
"heading": "Find us",
"paragraphs": ["12 Market Street, Hebden Bridge.", "Open Tuesday to Saturday, 9am to 5.30pm. Closed Mondays."]
},
{ "type": "footer", "text": "Ridgeway Cycles, Hebden Bridge" }
]
}
An example designed in its own code
{
"title": "Kiln Street Ceramics",
"theme": { "background": "#efe6da", "text": "#2b2118", "accent": "#a4512b", "font": "'Fraunces', Georgia, serif" },
"header": false,
"footer": false,
"head": "<link rel=\"stylesheet\" href=\"https://fonts.googleapis.com/css2?family=Fraunces:wght@400;700&display=swap\">",
"css": ".kiln-intro { min-height: 90vh; display: grid; place-items: center; text-align: center; padding: 4rem 1.5rem; background: #2b2118; color: #efe6da; }\n.kiln-intro h1 { font-size: clamp(3rem, 10vw, 7rem); margin: 0; }\n.kiln-intro a { color: #efe6da; }\n.classes { padding: 4rem 1.5rem; max-width: 48rem; margin: 0 auto; }",
"script": "document.querySelectorAll('.kiln-year').forEach(function (node) { node.textContent = new Date().getFullYear(); });",
"sections": [
{
"type": "html",
"id": "top",
"html": "<div class=\"kiln-intro\"><div><h1>Kiln Street</h1><p>Hand-thrown stoneware from a studio in Leeds.</p><p><a href=\"#classes\">Book a class</a> · <a href=\"mailto:hello@kilnstreet.example\">Email the studio</a></p></div></div>"
},
{
"type": "text",
"id": "classes",
"class": "classes",
"heading": "Wheel classes",
"paragraphs": ["Six Tuesday evenings, 7pm to 9pm, for six people at a time.", "Clay, glazes and two firings are included."]
},
{
"type": "html",
"html": "<p style=\"text-align:center;padding:2rem\">Kiln Street Ceramics, <span class=\"kiln-year\"></span></p>"
}
]
}
An example with a game
{
"title": "Space Rocks",
"theme": { "background": "#0b1020", "text": "#f4f4f8", "accent": "#ffcc33" },
"sections": [
{
"type": "hero",
"heading": "Space Rocks",
"lede": "Steer the ship with the left and right arrow keys.",
"button": { "label": "Play", "href": "#game" }
},
{
"type": "html",
"id": "game",
"html": "<div class=\"space-rocks\"><canvas width=\"480\" height=\"320\"></canvas></div>\n<style>\n.space-rocks { padding: 2rem; }\n.space-rocks canvas { display: block; max-width: 100%; background: #000; }\n</style>\n<script>\nconst canvas = document.querySelector('.space-rocks canvas');\nconst context = canvas.getContext('2d');\nlet x = 220;\ndocument.addEventListener('keydown', (event) => {\n if (event.key === 'ArrowLeft') x = Math.max(0, x - 20);\n if (event.key === 'ArrowRight') x = Math.min(440, x + 20);\n context.clearRect(0, 0, 480, 320);\n context.fillStyle = '#ffcc33';\n context.fillRect(x, 290, 40, 20);\n});\n</script>"
},
{ "type": "footer", "text": "Space Rocks" }
]
}
If an import is rejected for a reason you can't work out, Contact support.
Ask Magpie support
Send Magpie staff a question about anything this article does not answer.