# Custom code

> Add your own CSS, analytics, tag managers, and chat widgets to every page. Available on Pro and Enterprise.

Add your own styles, analytics, and widgets to your docs. Custom code is on Pro and Enterprise, and follows the project owner's plan.

There are three kinds:

- **Integrations**: Google Analytics 4, Plausible, Fathom, Google Tag Manager, Hotjar, and Intercom, set up with just their ID.
- **Custom CSS**: your own stylesheet on every page.
- **Head and body HTML**: any snippet a vendor gives you, such as an analytics tag or a chat widget.

## Where your code runs

Your site has up to two addresses: your custom domain and `your-project.typemark.dev`. Scripts you add run on your custom domain only.

| | Your custom domain | `your-project.typemark.dev` |
|---|---|---|
| Custom CSS | Yes | Yes |
| Head and body HTML, `.js` files | Yes | No |
| Google Analytics 4, Plausible, Fathom | Yes | Yes |
| Google Tag Manager, Hotjar, Intercom | Yes | No |

Your custom domain needs to be verified first. See [Custom domain](https://docs.typemark.dev/configuration/custom-domain).

<Callout type="info">
  Why the custom domain? Every `typemark.dev` address shares cookies with the Typemark app and with other customers' sites. So code you choose only runs on a domain that is yours alone. The three analytics integrations that also run on `typemark.dev` load a fixed script from their vendor, and Typemark keeps their cookies on your site's own address.
</Callout>

If you add scripts before your custom domain is verified, they're saved but don't run, and **Settings** > **Custom code** says so.

## Set it up in Settings

Go to **Settings** > **Custom code**, fill in what you need, and click **Save custom code**. Typemark commits the files and `typemark.json` to your repo and rebuilds your site.

- **Analytics and support**: paste an ID, such as `G-XXXXXXXXXX` for Google Analytics 4.
- **Custom CSS**, **Head HTML**, **Body HTML**: paste the code. Typemark saves it to `custom/styles.css`, `custom/head.html`, and `custom/body.html` in your repo.

Under each snippet, Settings lists anything that will be removed when it's published (see [What snippets can contain](#what-snippets-can-contain)). Clearing a box deletes its file.

## Integrations

Add the ID for each tool under `integrations` in `typemark.json`:

```json title="typemark.json"
"integrations": {
  "ga4": { "measurement_id": "G-XXXXXXXXXX" },
  "plausible": { "domain": "docs.example.com" },
  "fathom": { "site_id": "ABCDEFGH" },
  "gtm": { "container_id": "GTM-XXXXXXX" },
  "hotjar": { "site_id": "1234567" },
  "intercom": { "app_id": "abc12345" }
}
```

| Key | Where to find the ID | Runs on |
|-----|----------------------|---------|
| `ga4.measurement_id` | Google Analytics: **Admin** > **Data streams** > your web stream. Starts with `G-`. | Both addresses |
| `plausible.domain` | The site domain you added in Plausible | Both addresses |
| `fathom.site_id` | Fathom: **Settings** > **Sites** | Both addresses |
| `gtm.container_id` | Google Tag Manager, at the top of your workspace. Starts with `GTM-`. | Your custom domain |
| `hotjar.site_id` | Hotjar: **Sites & Organizations** | Your custom domain |
| `intercom.app_id` | Intercom: **Settings** > **Installation** > **Web** | Your custom domain |

An ID that doesn't look right is skipped, and the build lists it as a warning on your project's overview page. For any other tool, paste its snippet as [head HTML](#head-and-body-html).

## Copy-paste examples

<Tabs>
  <Tab title="Google Analytics 4">
    The ID is enough:

    ```json title="typemark.json"
    "integrations": {
      "ga4": { "measurement_id": "G-XXXXXXXXXX" }
    }
    ```

    Or paste Google's snippet as head HTML (custom domain only):

    ```html title="custom/head.html"
    <script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'G-XXXXXXXXXX');
    </script>
    ```

    Google Analytics counts page changes inside your docs on its own, as long as **Enhanced measurement** > **Page changes based on browser history events** is on for your web stream (it is by default).
  </Tab>
  <Tab title="Google Tag Manager">
    The ID is enough:

    ```json title="typemark.json"
    "integrations": {
      "gtm": { "container_id": "GTM-XXXXXXX" }
    }
    ```

    Or paste both parts of Google's snippet: the `<script>` as head HTML and the `<noscript>` as body HTML.

    ```html title="custom/head.html"
    <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
    new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
    j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
    'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
    })(window,document,'script','dataLayer','GTM-XXXXXXX');</script>
    ```

    ```html title="custom/body.html"
    <noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-XXXXXXX"
    height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
    ```

    To count page changes inside your docs, add a **History Change** trigger to your page view tag. With the `gtm` integration, Typemark also pushes a `typemark_page_view` event to the data layer, for a **Custom Event** trigger. It carries `page_location`, `page_path`, and `page_title`.
  </Tab>
  <Tab title="Plausible">
    The domain is enough:

    ```json title="typemark.json"
    "integrations": {
      "plausible": { "domain": "docs.example.com" }
    }
    ```

    Or paste Plausible's snippet as head HTML (custom domain only), for example to use your own Plausible server:

    ```html title="custom/head.html"
    <script defer data-domain="docs.example.com" src="https://plausible.io/js/script.js"></script>
    ```

    Plausible counts page changes inside your docs on its own.
  </Tab>
  <Tab title="Intercom">
    The app ID is enough:

    ```json title="typemark.json"
    "integrations": {
      "intercom": { "app_id": "abc12345" }
    }
    ```

    Or paste Intercom's snippet as body HTML (custom domain only):

    ```html title="custom/body.html"
    <script>
      window.intercomSettings = { api_base: "https://api-iam.intercom.io", app_id: "abc12345" };
    </script>
    <script>
      (function(){var w=window;var ic=w.Intercom;if(typeof ic==="function"){ic('reattach_activator');ic('update',w.intercomSettings);}else{var d=document;var i=function(){i.c(arguments);};i.q=[];i.c=function(args){i.q.push(args);};w.Intercom=i;var l=function(){var s=d.createElement('script');s.type='text/javascript';s.async=true;s.src='https://widget.intercom.io/widget/abc12345';var x=d.getElementsByTagName('script')[0];x.parentNode.insertBefore(s,x);};if(document.readyState==='complete'){l();}else if(w.attachEvent){w.attachEvent('onload',l);}else{w.addEventListener('load',l,false);}}})();
      document.addEventListener('typemark:page-view', function () { window.Intercom('update'); });
    </script>
    ```

    The last line tells Intercom when a reader moves to another page. The `intercom` integration does this for you.
  </Tab>
</Tabs>

## Custom CSS

Your CSS loads after Typemark's, on every page of your custom domain and `your-project.typemark.dev`, so your rules win when they're as specific as ours.

```css title="custom/styles.css"
@import url("https://fonts.googleapis.com/css2?family=Inter:wght@600&display=swap");

/* Your brand font for page headings */
article h1,
article h2 {
  font-family: "Inter", sans-serif;
}

/* Rounder images */
article img {
  border-radius: 0.75rem;
}
```

- Load fonts with an `@import` from Google Fonts at the top of your first CSS file, or put the font files in your repo and use paths that start with `/assets/`, such as `url(/assets/fonts/brand.woff2)`. Fonts from other services load only on a custom domain that also has scripts.
- Typemark's class names can change between releases. Target elements, such as `article` and `nav`, where you can.
- Custom CSS can be up to 256 KB.

## Head and body HTML

Head HTML goes at the end of `<head>` on every page, and body HTML at the end of `<body>`. Both run on your custom domain only.

### What snippets can contain

Typemark rebuilds each snippet from the parts it allows, so a snippet can't break the page around it:

- **Tags**: `<script>`, `<noscript>`, `<link>`, `<meta>`, and `<style>`. Other tags, such as a `<div>` around a script, are removed, and the tags inside them are kept.
- **`<script>`**: inline code, or a `src` that starts with `https://`. Attributes like `async`, `defer`, `type`, `id`, `crossorigin`, `integrity`, and any `data-` attribute are kept. Event handlers such as `onload` are removed.
- **`<noscript>`**: an `<iframe>` or `<img>` with an `https://` source, for readers without JavaScript. A `<noscript>` in head HTML is moved to the body.
- **`<link>`**: `stylesheet`, `preconnect`, `dns-prefetch`, `preload`, `modulepreload`, `prefetch`, `me`, `alternate`, `author`, and `license`. Typemark sets the canonical link and icons itself.
- **`<meta>`**: `name` or `property` with `content`, such as a site verification tag. `http-equiv` isn't allowed.
- Each of head and body HTML can be up to 64 KB.

Scripts loaded by your scripts work too: tag managers and chat widgets can load what they need, and your site allows connections, frames, and fonts from any `https://` address.

### Count page views in your own tools

Your docs change pages without a full reload. Most analytics tools notice this on their own. For anything else, listen for the `typemark:page-view` event. Typemark sends it on `document` after each page change, with the new page's address and title. It isn't sent for the first page a reader opens, which your tool counts when it loads.

```html title="custom/body.html"
<script>
  document.addEventListener('typemark:page-view', function (event) {
    // event.detail.url, event.detail.path, event.detail.title
    myAnalytics.page(event.detail.path);
  });
</script>
```

## In your repository

The `custom_code` key points to files in your repository. Each value is a path or a list of up to 10 paths, relative to the repository root.

```json title="typemark.json"
"custom_code": {
  "css": "custom/styles.css",
  "head": "custom/head.html",
  "body": ["custom/body.html", "scripts/widget.js"]
}
```

| Key | Files | Limit |
|-----|-------|-------|
| `css` | `.css` | 256 KB in all |
| `head` | `.html` snippets or `.js` files | 64 KB in all |
| `body` | `.html` snippets or `.js` files | 64 KB in all |

A `.js` file runs as an inline script. A file that's missing, too large, or of another type is skipped, and the build lists it as a warning on your project's overview page. **Settings** > **Custom code** edits the first file of each list.

Coming from Mintlify? The import lists your `.css` and `.js` files here and copies your `integrations`. See [Migrating from Mintlify](https://docs.typemark.dev/migrating/mintlify).

## If you change plans

On the Free plan, your site stops loading custom CSS, scripts, and integrations, but `typemark.json` and your files stay as they are. Upgrade again and they're back at once.
