feat: manually set contents of <head /> tag #5087

bguiz · 2026-04-02T09:59:05Z

bguiz
Apr 2, 2026

Global level
- In docs.json, have a config option where you can set custom elements (including <script /> tags, just like used to be possible via mint.json
- These should be applied site-wide
- Render those statically, i.e. when a browser/ crawl bot first loads the page, without executing any JS, the tags are already present
Per-page
- In the YAML frontmatter of each page, have a config option where you can set custom elements (including <script /> tags, just like used to be possible via mint.json
- This should be applied to just this page
- Render those statically, i.e. when a browser/ crawl bot first loads the page, without executing any JS, the tags are already present

using seo.metatags within docs.json
- this is specific to meta tags
adding <script /> tags into the body of the .mdx files
- this gets converted into JS that needs to be rendered in the browser, and is not available during a static render
using custom scripts as described in: https://www.mintlify.com/docs/customize/custom-scripts
- this also gets converted into JS that needs to be rendered in the browser, and is not available during a static render
modify the HTML template used by mintlify
- Mintlify does not provide this option
Used Microdata instead of JSON-LD
- Even though this is pure XML, this too gets converted into JS that needs to be rendered in the browser, and is not available during a static render

Use GTM to insert the <script /> tags
- This works at a global level - i.e. if I want to set the same one for every page on the site - so it is at best a partial solution
- This is also extremely hacky/ not elegant, as I cannot commit these files into the git repo for my site, and hence it doesn't get versioned properly

I would like to set custom JSON-LD for rich data as this is read/ used by Google
- This is the proper/ recommended way by Google
SEO and GEO are negatively impacted without this
- SEO and GEO audit tools explicitly look for the presence of correct types of JSON-LD
- Google explicitly looks for specific JSON-LD items when crawling, and displays them in search results
Note that this used to be possible with mint.json, however that has been deprecated