Skip to main content

Overview

Mintlify allows you to add custom JavaScript files to your documentation site through the docs.json configuration file. Custom scripts are included across all pages of your documentation.

Installation

Get the JavaScript snippet from the CustomerOS app - it’s specific to your domain so that you aren’t blocked by adblockers and privacy modes.
  1. In your Mintlify project’s root directory, create a new JavaScript file:
    touch customeros-tracker.js
    
  2. Open customeros-tracker.js and paste the JavaScript code from the CustomerOS app
  3. Update your docs.json file to include the custom script:
    {
        "settings": {
            "customScripts": ["/customeros-tracker.js"]
        }
    }
    
    If you already have a settings section, just add the script to the customScripts array:
    {
        "settings": {
            "customScripts": ["/customeros-tracker.js", "/other-script.js"]
        }
    }
    
  4. Commit and push the files to your repository:
    git add customeros-tracker.js docs.json
    git commit -m "Add CustomerOS tracker"
    git push
    
  5. Deploy your Mintlify site
The tracker will now be automatically included on all pages of your documentation.
The JavaScript file should be placed in the root directory of your Mintlify project, and the path in docs.json should start with /.

Verifying Installation

After deploying your site:
  1. Visit your Mintlify documentation
  2. Open your browser’s developer console (F12 or right-click → Inspect)
  3. Check the Network tab for a request to your tracker domain
  4. Look for successful 200s and 202s from the tracker subdomain
  5. Check the Console tab for any errors
You should see page views appearing in your CustomerOS dashboard within a few minutes.

Troubleshooting

If the tracker isn’t working:
  • Ensure the .js file is in the root directory of your project
  • Check that the script path is correctly added to docs.json in the settings.customScripts array
  • Verify the path starts with / (e.g., /customeros-tracker.js)
  • Check that you’ve deployed the changes to your Mintlify site
  • Verify that your tracker domain is correct and accessible
  • Check the browser console for any JavaScript errors
For more help, see our Troubleshooting guide.

Additional Resources

I