Open this in Magpie

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's slug when 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": false takes away the header every page shares, with the website's name and its pages. "footer": false takes away the shared footer. "header": true puts the starter design's header back.
  • Your own styles for the whole site. css is a stylesheet for every page, placed after the design's own, so its rules win. Give any section a class and style it there.
  • Fonts and other head tags. head holds tags for the page's <head>, such as a <link> to a font. theme.font sets the font the design uses.
  • A script for every page. script is JavaScript that runs on every page.
  • Any part, or all of it, in your own code. An html section has no padding or styles of its own, so it can run edge to edge. One html section can be the whole page, or html sections can sit between hero, text and list sections.

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 one html section.
  • In the editor, the page replaces the open page's sections as one html section, 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 html section 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, css and script applied.

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>" }
  ]
}

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 as magpie:page/about, or magpie:page/ for the home page;
  • a full address starting http:// or https://;
  • a mailto: or tel: link, such as mailto:hello@example.com or tel:+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 one html section 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 for body, html or * changes every page.
  • To design the whole page yourself, use "header": false, "footer": false, one or more html sections and css. The starter design's stylesheet still styles plain elements such as headings and paragraphs, and css comes after it, so its rules win. For a page with nothing of the starter design, put a whole page of HTML in the only html section of a document with "replace": "design", or paste the page on New website.
  • A script finds its elements by a class or id of its own. A script or stylesheet from another site needs its full https:// 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.