Custom code¶

Sometimes you need to add code that the visual editor does not cover -- an analytics tracker, a custom font, a CSS framework, or a meta tag. The Settings dialog includes a code editor for the <head> tag, and the Custom Code block lets you embed arbitrary HTML and JavaScript anywhere on the page.

Two things to keep in mind:

Head code runs on every page (site level) or one page (page level). Choose the right scope so tracking scripts do not fire where they should not.
Custom code blocks are part of the page content. They live inside the <body> and render wherever you place them on the canvas.

The head editor¶

The head editor is a code editor inside the Code tab of the Settings dialog. It lets you write HTML that will be injected directly into the <head> element of your published pages.

Opening the head editor¶

Click Settings in the left sidebar (Alt+S) to open Site Settings.
Select the Code tab.
You will see a code editor with syntax highlighting and line numbers.
Write your HTML.
Click Apply (or press Ctrl+Enter).

The Code settings tab with an HTML editor for inserting custom code in the HEAD tag

Site-level vs. page-level head code¶

When you open Site Settings and add code in the Code tab, that code appears in the <head> of every page on your site. When you open Page Settings (gear icon next to the page in the Pages panel) and add code, it only applies to that one page.

Both are injected. They do not replace each other. If you have site-level head code and page-level head code, both will be present in the published HTML -- the site code first, then the page code.

This means you can:

Add an analytics tracker (for example Matomo) at the site level so it tracks every page.
Add a page-specific canonical tag or a noindex directive on individual pages without affecting the rest of the site.

Live preview¶

When you apply head code, the editor adds it to the canvas preview. If you add a stylesheet or a <style> block, you see its effects right away. Scripts do not run in the editor preview. They only run on the published site, so test them there.

Common use cases for head code¶

A self-hosted font¶

The Fonts dialog installs Google Fonts for you. For another font, for example a font file you host yourself, load it in the head editor with a <style> block:

<style>
  @font-face {
    font-family: "My Font";
    src: url("https://www.example.com/fonts/my-font.woff2") format("woff2");
    font-weight: 400;
    font-style: normal;
    font-display: swap;
  }
  .my-title {
    font-family: "My Font", sans-serif;
  }
</style>

Replace My Font with the name of your font, and the address with the address of your font file.

The .my-title rule applies the font. Give the class my-title to the elements that use this font.

It will not appear in the font-family dropdown

The font-family field of the Style panel is a dropdown. It only lists fonts added through the Fonts dialog, and you cannot type a font name in it. A font loaded from head code is not in this list, so apply it with CSS in the same <style> block, as shown above.

Tip: Add the font at the site level so it is available on all pages. If you only add it on one page, elements using that font on other pages will fall back to a default.

Matomo¶

Matomo is a free and open source analytics tool. Add its tracking code to measure visits across your entire site:

<!-- Matomo -->
<script>
  var _paq = window._paq = window._paq || [];
  /* tracker methods like "setCustomDimension" should be called before "trackPageView" */
  _paq.push(['trackPageView']);
  _paq.push(['enableLinkTracking']);
  (function() {
    var u="https://YOUR-MATOMO-ADDRESS/";
    _paq.push(['setTrackerUrl', u+'matomo.php']);
    _paq.push(['setSiteId', 'YOUR-SITE-ID']);
    var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
    g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s);
  })();
</script>
<!-- End Matomo Code -->

Replace YOUR-MATOMO-ADDRESS with the address of your Matomo instance (for example matomo.example.com), and YOUR-SITE-ID with the ID of your site in Matomo. Matomo shows the full code with these values in its tracking code settings. Add this at the site level so tracking works on every page.

Custom CSS¶

Add a <style> block to define styles that the visual editor does not support or that you want to write by hand:

<style>
  /* Smooth scrolling for anchor links */
  html {
    scroll-behavior: smooth;
  }

  /* Custom selection color */
  ::selection {
    background-color: #3b82f6;
    color: white;
  }
</style>

When to use this vs. the Style panel: Use the Style panel for element-specific styles you want to manage visually. Use custom CSS in the head for global behaviors, pseudo-elements, animations, or anything the Style panel does not expose.

Canonical tags¶

Tell search engines which URL is the original version of a page:

<link rel="canonical" href="https://www.example.com/my-page">

Add this at the page level because each page has its own canonical URL. See SEO for more on why canonical tags matter.

Robots meta tag¶

Prevent search engines from indexing a specific page:

<meta name="robots" content="noindex, nofollow">

Add this at the page level on draft pages, thank-you pages, or admin pages. Do not add it at the site level unless you want your entire site hidden from search engines.

External CSS frameworks¶

Load a CSS framework like Normalize.css or a utility library:

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/normalize/8.0.1/normalize.min.css">

Add at the site level if you want the framework on every page.

Verification tags¶

Many services (Google Search Console, Bing Webmaster Tools, Pinterest) ask you to verify site ownership by adding a meta tag:

<meta name="google-site-verification" content="your-verification-code">

Add this at the site level. It only needs to be on one page (usually the homepage), but having it on all pages does no harm.

Custom code blocks¶

The head editor is for code in the <head>. But sometimes you need to embed HTML, CSS, or JavaScript inside the page body itself -- a contact form widget, an embedded video player, a live chat button, or an interactive element.

For this, use the Custom Code block. It lets you place a block of arbitrary HTML anywhere on your canvas.

Adding a custom code block¶

Open the Blocks panel (the + icon in the left sidebar).
Find the Custom Code block, in the Elements category.
Drag it onto the canvas where you want it. The Insert your code dialog opens.
Write or paste your HTML, CSS, or JavaScript.
Click Save.

To change the code later, double-click the block.

The block renders your HTML on the canvas. If your code contains a <script>, the canvas shows the message Custom code with <script> can't be rendered on the canvas instead. The script runs on the published site.

Use cases for custom code blocks¶

Embed a form. Paste the embed code from a form service (Typeform, Google Forms, Tally, etc.) into a custom code block. The form appears on your page wherever you placed the block.

Add an interactive widget. Chat widgets, appointment booking tools, and social media feeds often provide embed codes. Paste them into a custom code block.

JavaScript-powered elements. If you need an element that requires JavaScript -- a slideshow, an accordion, a dynamic counter -- write it in a custom code block. The JavaScript executes in the browser when the page loads.

Embedded maps. Google Maps and OpenStreetMap provide <iframe> embed codes that you can paste into a custom code block.

Custom code blocks vs. head code¶

	Head editor (Code tab)	Custom code block
Location in HTML	Inside `<head>`	Inside `<body>`, wherever you place it
Scope	Site-wide or per-page	Only on the page where you add it
Typical content	Meta tags, stylesheets, analytics, fonts	Forms, widgets, embeds, interactive elements
Visible on canvas	No (head content is invisible)	Yes, except code with a `<script>`
How to add	Settings dialog > Code tab	Drag Custom Code block from the Blocks panel

Common mistakes¶

Adding a <script> in the head that should be in the body. Analytics and fonts belong in the head. Interactive widgets and embed codes belong in custom code blocks in the body.
Forgetting to set the right scope. Site-level head code runs on every page. If you add a page-specific canonical tag at the site level, every page gets the same canonical URL -- which is wrong.
Not testing after publishing. The editor preview is close to the published result, but not identical. Always verify on the live site.

Advanced: execution order and interaction between site and page head code

Injection order¶

When a page is published, the head code is injected in this order:

The charset, viewport and generator meta tags
The Silex stylesheet of your site
Site-level custom head code
Page-level custom head code
The title, favicon, description and Open Graph tags

This means your custom styles come after the Silex stylesheet, and page-level code can override site-level styles (later CSS rules win). Page-level scripts run after site-level scripts.

Overriding site-level styles¶

If your site-level head code adds a stylesheet and you want to override a specific style on one page, add a <style> block in that page's head code with a more specific selector or the same selector (it wins because it comes later in the document).

Avoiding duplicate scripts¶

If you load the same script at both the site level and the page level, it will execute twice. This can cause errors or double-counting in analytics. Use site-level for scripts that should run everywhere. Use page-level only for scripts unique to that page.

Quiz¶

Q1: You want to add Matomo tracking to your entire site. Where do you put the tracking code?

A) In a Custom Code block on the homepage
B) In the Code tab of Site Settings
C) In the Code tab of each page's Page Settings

Answer

B) In the Code tab of Site Settings. Site-level head code runs on every page, which is what you want for analytics. Option A only tracks the homepage. Option C works but requires adding the code to every page manually.

Q2: You pasted a contact form embed code into the head editor, but nothing appears on the page. What went wrong?

A) The embed code is broken
B) The head editor injects code into the <head>, which is invisible -- form embed codes should go in a Custom Code block in the body
C) You need to add CSS to make it visible

Answer

B) The head editor is for invisible <head> content. Forms and other visible elements belong in a Custom Code block, which renders inside the page body. The <head> is for meta tags, stylesheets, and scripts -- not visible HTML.

Q3: You loaded a font in the head editor of one page's Page Settings. On other pages, text set to that font looks wrong. Why?

A) A font can only be used on one page
B) The font is only loaded on the page where you added it, other pages do not have it
C) You need to clear the browser cache

Answer

B) The font is only loaded on the page where you added it. Add fonts at the site level so they are available on every page. Page-level head code only applies to that specific page.

Q4: You want to prevent your "Thank You" page from appearing in search results. What do you add, and where?

A) <meta name="robots" content="noindex, nofollow"> in the Code tab of that page's Page Settings
B) <meta name="robots" content="noindex, nofollow"> in the Code tab of Site Settings
C) Remove the page title in SEO settings

Answer

A) Add the robots meta tag in that page's Page Settings Code tab. This hides only that page from search engines. Adding it at the site level would hide your entire site. Removing the title does not prevent indexing.

Edit this page on GitLab