Build a website by pasting JSON

A JSON document describes a website's sections and what they say; Magpie builds the page from it in the starter design. 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. The website's name and address come from the document, not from the Name field.
• In the editor of a website you already have, Import JSON… in More, then Replace the page, replaces every section on the open page with the document's. The layout every page shares (its head, stylesheet, header and footer) is kept, so changes you have made to the design remain. The document's theme colours apply to every page, and a footer section replaces the footer every page shares.

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, its colours and its sections before it writes anything.

Importing in the editor changes the draft. The new sections replace the open page's draft, and visitors will see them once you publish. To go back, 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.

Only an html section contains HTML. For every other section you describe the words and Magpie writes the markup into the starter design. An html section carries its own markup, styles and script, for a game, a quiz or a calculator. The result is an ordinary website afterwards: edit it in Visual mode or Code mode like any other.

An imported website is not published. Choose Publish in the editor 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 section that caused it.

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 comes from the page's <title>, or its first <h1> when it has no title; a page with neither is refused until you add a <title>. 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. Its styles and scripts are kept. Its title and meta tags are left out, because the website has its own.

Scripts run on the published website, not in the editor. The editor's preview shows an html section without running its script, so a game drawn by its script is blank there. Publish the website and open it to play.

The document

{
  "title": "Ridgeway Cycles",
  "slug": "ridgeway-cycles",
  "theme": { "background": "#f5f1e8", "text": "#1d1d1b", "accent": "#b74232" },
  "nav": [],
  "sections": []
}

A href is either an anchor on this page (# followed by lowercase letters, numbers and hyphens) or a full address starting http:// or https://. Nothing else is accepted.

Sections

Every section names a type and supplies the fields that type uses. type defaults to text.

Give a section an id whenever a nav link or a hero button points at it.

Writing an html section

An html section is one band of a page that also has the website's header, other sections and footer. Write it so that it changes nothing outside itself:

• Put everything the section needs in its html: the markup, one <style> and one <script>. A script or stylesheet from another site needs its full https:// address.
• Wrap the markup in one element with a class of its own, such as <div class="space-rocks">, and start every CSS rule with that class (.space-rocks canvas). A rule for body, html or * changes the whole website.
• Have the script find its elements inside that wrapper and draw there. A script that adds elements to document.body puts them outside the section.
• 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 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 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.