Putting Monocle on my Website

Goal of this tutorial

This guide aims to help you add Monocle Search to your non-Squarespace website. If you are using Squarespace, please check out the getting-started-guide for Squarespace websites.

Part 1: Signing up

• On monocle-search.com, click on Register in the upper right corner.
• Make sure to click on the "Register with e-mail and password"-button
• Enter your email, a password, and any other information the form is asking for, and click on “Create an account”.

Part 2: Setting up Monocle

• You’re in! Now you have to let Monocle know which site you want to have the search feature on. Put your site’s URL in the “URL” field and click on "Start trial". For the purpose of this tutorial, I’ll be using https://demo.monocle-search.com

  

• Success! While you’re digesting the next steps, Monocle is working away in the background and “indexing” your site, which means it’s reading and sorting all available content. You’re only two tasks away from having a blazingly fast search bar on your site now!
• Now we need to add a script to your site. You should see the following instructions (with a different code in siteID:

  

  Just click on the little clipboard in the upper right, or select and copy the script.

The exact steps needed to add this script to your website depends on what website builder you are using. If you are using a static website builder (like jekyll, next.js, astro, etc) you likely have a layout file where you can add it.

If you are using the website builder Cargo Collective, please check out our Cargo Collective-specific guide.

If you do not know how to proceed from here, please contact us, and we will do our best to help you out!

Part 3: Activating the search interface

Monocle Search can be activated in a number of different ways:

• any link that has the destination of /search, will open up the search interface
• any input of type search will automatically be upgraded to use Monocle

Link to /search

The preferred method of activating Monocle Search is through a link to /search. The link might look something like this:

<a href="/search">Search</a>

(you can of course style it as you please, or even add a custom SVG-icon - for example from heroicons to make it match your brand and style).

Adding a search input

If you prefer to have a search input on your website, you can add one, with the following HTML:

<input
  type="search"
  placeholder="Search my site"
  style="width: 300px; border: 1px solid #ccc; padding: 0.5rem; border-radius: 4px"
/>

If will result in a search interface looking something like this:

Programatic activation

If you are a developer, and not afraid of getting your feet wet, you can also use one of our custom means of activating Monocle Search. With the script-tag loaded on your site, you will have the Monocle object available under window. Take a peak at what's available there, and feel free to contact us if you want some guidance.

For example, you can do something like the following, to have any input with the id of search render the search result into a DOM-node with id results:

<script type="module">
  let monocleReady = false;

  function tryInitialiseSearch(input) {
    const mount = document.getElementById("results");
    if (!mount || !window.Monocle)
        return false;

    window.Monocle.createCustomInterface(input, mount);
    return true;
  }

  function handleFocus(event) {
    const {target} = event;
    if (monocleReady || target.id !== "search")
        return;

    try {
        monocleReady = tryInitialiseSearch(target);
        if (monocleReady)
            document.removeEventListener("focusin", handleFocus);
    } catch (err) {
        console.error("Failed to initialise Monocle Search:", err);
    }
  }

  document.addEventListener("focusin", handleFocus);
</script>

Part 4: Tweaking Monocle Search

With the Monocle Search integration added to your site, make sure you also check out the other features we offer in our administrative interface!

These include features to alter the design of the built in search widgets, and exclude pages you do not want to appear in search.

Congratulations!

This concludes our tutorial. Please do not hesitate to contact us if you got stuck anywhere along the process of adding, using, or customizing Monocle Search. While the onboarding experience for non-Squarespace-users isn't quite as straight forward as it is for those using Squarespace, we love to see that people use our search engine in creative ways.