BUG: notebook metadata `date` is not JSON serializable

[bsipocz]

trafficstars

Description

I would like to add notebook level metadata (authors and date) to override the project wide one, yet I run into this datetime issue. I suppose this maybe more a jupyter client issue (please advise where to propagate it upstream); but I also see it as a mystmd bug as I was using a format that the documentation listed as a valid one.

[W 2025-10-07 16:38:18.630 ServerApp] wrote error: 'Unhandled error'
    Traceback (most recent call last):
      File "/Users/bsipocz/.pyenv/versions/3.12.1/lib/python3.12/site-packages/tornado/web.py", line 1790, in _execute
        result = await result
                 ^^^^^^^^^^^^
      File "/Users/bsipocz/.pyenv/versions/3.12.1/lib/python3.12/site-packages/jupyter_server/auth/decorator.py", line 73, in inner
        return await out
               ^^^^^^^^^
      File "/Users/bsipocz/.pyenv/versions/3.12.1/lib/python3.12/site-packages/jupyter_server/services/contents/handlers.py", line 178, in get
        self._finish_model(model, location=False)
      File "/Users/bsipocz/.pyenv/versions/3.12.1/lib/python3.12/site-packages/jupyter_server/services/contents/handlers.py", line 109, in _finish_model
        self.finish(json.dumps(model, default=json_default))
                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/Users/bsipocz/.pyenv/versions/3.12.1/lib/python3.12/json/__init__.py", line 238, in dumps
        **kw).encode(obj)
              ^^^^^^^^^^^
      File "/Users/bsipocz/.pyenv/versions/3.12.1/lib/python3.12/json/encoder.py", line 200, in encode
        chunks = self.iterencode(o, _one_shot=True)
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/Users/bsipocz/.pyenv/versions/3.12.1/lib/python3.12/json/encoder.py", line 258, in iterencode
        return _iterencode(o, 0)
               ^^^^^^^^^^^^^^^^^
      File "/Users/bsipocz/.pyenv/versions/3.12.1/lib/python3.12/site-packages/jupyter_client/jsonutil.py", line 125, in json_default
        raise TypeError("%r is not JSON serializable" % obj)
    TypeError: datetime.date(2025, 9, 30) is not JSON serializable

This was the header metadata in my example:

jupytext:
  text_representation:
    extension: .md
    format_name: myst
    format_version: 0.13
    jupytext_version: 1.17.3
kernelspec:
  display_name: Python 3 (ipykernel)
  language: python
  name: python3
authors:
  - name: Brigitta Sipőcz
  - name: IRSA Data Science Team
date: 2025-09-30

It understands date: Tue, 30 Sep 2025, a format I really not prefer to use.

Proposed solution

• [ ] fix upstream
• [ ] fix the docs to only list formats that jupyter accepts, too, in addition that ones that the rendering understands

Additional notes

I suppose we should explore to be more comprehensive testing the notebook experience.