Skip to content

add html_head parameter to create_asgi_app()#8302

Merged
mscolnick merged 3 commits intomarimo-team:mainfrom
nojaf:create_asgi_app-html-head
Feb 23, 2026
Merged

add html_head parameter to create_asgi_app()#8302
mscolnick merged 3 commits intomarimo-team:mainfrom
nojaf:create_asgi_app-html-head

Conversation

@nojaf
Copy link
Contributor

@nojaf nojaf commented Feb 13, 2026

📝 Summary

Adds an html_head parameter to marimo.create_asgi_app() that injects custom HTML into the <head> of every notebook served through the ASGI app, without requiring per-notebook configuration.

🔍 Description of Changes

ASGI deployers often need to inject global snippets (analytics, custom fonts, meta tags) into every notebook page. Previously this was only possible per-notebook via App(html_head_file="..."). This PR adds an html_head string parameter to create_asgi_app() for global injection.

Usage:

app = (
    create_asgi_app(
        html_head='<script src="https://analytics.example.com/tracker.js"></script>',
    )
    .with_app(path="/", root="app.py")
    .build()
)

How it works:

  • create_asgi_app(html_head=...) stores the string and sets it on each sub-app's app.state.html_head.
  • AppStateBase.html_head property exposes it (with hasattr fallback for non-ASGI contexts).
  • The index() handler passes it to notebook_page_template().
  • notebook_page_template() injects it before </head>, before any per-notebook html_head_file content. This means both are additive and per-notebook content takes priority on conflicts.

Files changed:

File Change
marimo/_server/asgi.py New html_head param, docstring, app.state.html_head
marimo/_server/api/deps.py html_head property on AppStateBase
marimo/_server/api/endpoints/assets.py Pass html_head to template
marimo/_server/templates/templates.py Inject global html_head before per-notebook content
tests/_server/templates/test_templates.py 2 new tests (global-only, global + per-notebook ordering)
tests/_server/test_asgi.py 3 new tests (state propagation, default, end-to-end)

📋 Checklist

  • I have read the contributor guidelines.
  • For large changes, or changes that affect the public API: this change was discussed or approved through an issue, on Discord, or the community discussions (Please provide a link if applicable).
  • Tests have been added for the changes made.
  • Documentation has been updated where applicable, including docstrings for API changes.
  • Pull request title is a good summary of the changes - it will be used in the release notes.

@vercel
Copy link

vercel bot commented Feb 13, 2026 •
edited
Loading

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
marimo-docs Ready Ready Preview, Comment Feb 13, 2026 8:18pm

Request Review

@mscolnick mscolnick requested a review from Copilot February 13, 2026 17:29
Copilot AI reviewed Feb 13, 2026
View reviewed changes
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a new html_head parameter to marimo.create_asgi_app() to support injecting a global HTML snippet into the <head> of every notebook page served via the ASGI builder, without requiring per-notebook configuration.

Changes:

  • Add html_head: Optional[str] to create_asgi_app() and propagate it via app.state.html_head to sub-apps.
  • Expose html_head via AppStateBase.html_head and pass it through the index handler into notebook_page_template().
  • Inject global html_head into the HTML template before per-notebook html_head_file content; add tests covering propagation and ordering.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file
File Description
marimo/_server/asgi.py Adds the html_head builder parameter and stores it on each created sub-app’s app.state.
marimo/_server/api/deps.py Adds AppStateBase.html_head accessor with a safe fallback for states without the attribute.
marimo/_server/api/endpoints/assets.py Passes app_state.html_head into the notebook page template rendering path.
marimo/_server/templates/templates.py Adds html_head param to notebook_page_template() and injects it into <head> before per-notebook head file content.
tests/_server/templates/test_templates.py Adds tests for global-only injection and ordering vs per-notebook html_head_file.
tests/_server/test_asgi.py Adds tests for state propagation, default None, and end-to-end HTML injection in responses.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@mscolnick mscolnick added the enhancement New feature or request label Feb 22, 2026
@mscolnick mscolnick requested a review from akshayka February 22, 2026 23:13
mscolnick
mscolnick approved these changes Feb 23, 2026
View reviewed changes
Copy link
Contributor

@mscolnick mscolnick left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

looks good

@mscolnick mscolnick merged commit 5448916 into marimo-team:main Feb 23, 2026
39 of 43 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

@mscolnick mscolnick mscolnick approved these changes

@akshayka akshayka Awaiting requested review from akshayka

Assignees

No one assigned

Labels

api-change enhancement New feature or request

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@nojaf @mscolnick