Custom code
Add your own CSS, analytics, tag managers, and chat widgets to every page. Available on Pro and Enterprise.
Updated Nov 19, 20265 min read
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.
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-XXXXXXXXXXfor Google Analytics 4. - Custom CSS, Head HTML, Body HTML: paste the code. Typemark saves it to
custom/styles.css,custom/head.html, andcustom/body.htmlin 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" }
}
| 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.
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).
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
@importfrom 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 asurl(/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
articleandnav, 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 asrcthat starts withhttps://. Attributes likeasync,defer,type,id,crossorigin,integrity, and anydata-attribute are kept. Event handlers such asonloadare removed.<noscript>: an<iframe>or<img>with anhttps://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, andlicense. Typemark sets the canonical link and icons itself.<meta>:nameorpropertywithcontent, such as a site verification tag.http-equivisn'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"]
}
| 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.
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.