Typemark Documentation

Custom code

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

Uuendatud 19. nov 20265 min lugemist

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 domainyour-project.typemark.dev
Custom CSSYesYes
Head and body HTML, .js filesYesNo
Google Analytics 4, Plausible, FathomYesYes
Google Tag Manager, Hotjar, IntercomYesNo

Your custom domain needs to be verified first. See Custom domain.

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). Clearing a box deletes its file.

Integrations

Add the ID for each tool under integrations in 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" }
}
KeyWhere to find the IDRuns on
ga4.measurement_idGoogle Analytics: Admin > Data streams > your web stream. Starts with G-.Both addresses
plausible.domainThe site domain you added in PlausibleBoth addresses
fathom.site_idFathom: Settings > SitesBoth addresses
gtm.container_idGoogle Tag Manager, at the top of your workspace. Starts with GTM-.Your custom domain
hotjar.site_idHotjar: Sites & OrganizationsYour custom domain
intercom.app_idIntercom: Settings > Installation > WebYour 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.

Copy-paste examples

The ID is enough:

"integrations": {
  "ga4": { "measurement_id": "G-XXXXXXXXXX" }
}

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

<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).

The ID is enough:

"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.

<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>
<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.

The domain is enough:

"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:

<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.

The app ID is enough:

"integrations": {
  "intercom": { "app_id": "abc12345" }
}

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

<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.

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.

@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.

<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.

"custom_code": {
  "css": "custom/styles.css",
  "head": "custom/head.html",
  "body": ["custom/body.html", "scripts/widget.js"]
}
KeyFilesLimit
css.css256 KB in all
head.html snippets or .js files64 KB in all
body.html snippets or .js files64 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.

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.