Skip to content

feat(notebooks): add --markdown to get, create, update, and edit - #750

Draft
andyjmorgan wants to merge 1 commit into
DataDog:mainfrom
andyjmorgan:feat/notebooks-markdown
Draft

feat(notebooks): add --markdown to get, create, update, and edit#750
andyjmorgan wants to merge 1 commit into
DataDog:mainfrom
andyjmorgan:feat/notebooks-markdown

Conversation

@andyjmorgan

@andyjmorgan andyjmorgan commented Aug 21, 2026

Copy link
Copy Markdown
Contributor

Summary

Work with a notebook as a Markdown document instead of a JSON cells array:

pup notebooks get 12345 --markdown                      # print as Markdown
pup notebooks create --markdown --file doc.md           # create from Markdown
pup notebooks update 12345 --markdown --file doc.md     # replace the document
pup notebooks edit 12345 --markdown --file fragment.md  # append server-side

These hit /api/unstable/notebooks, not yet promoted to /api/v2, so the flags are marked experimental in --help.

Changes

  • edit --markdown appends via the content-fragment endpoint. The JSON path fetches, splices, and rewrites the whole notebook; this does not.
  • --jq is rejected with --markdown, keyed on the flag rather than cfg.jq so an inherited PUP_FILTER does not block extension subprocesses.
  • JSON files passed with --markdown are rejected before any request.
  • The 5xx for notebooks with no Markdown projection becomes an actionable message. On writes it says the outcome is unknown — the render runs after the mutation, so a failure does not prove the write was rejected.
  • Raw-text print helper moved to util_ext::print_text_document; skills remote get had the same inline idiom.

Testing

  • All four commands, request bodies and media types, content-type and empty-body guards, JSON-file and BOM-prefixed-JSON rejection, both error-translation paths.
  • Against the live API: get returns frontmatter plus body, create creates, edit appends without disturbing existing content, update replaces, and a cells-era notebook gives the translated error rather than a raw 5xx.

Known gaps

  • Rich-text notebooks only. Notebooks from the older cells API have no Markdown projection.
  • update --markdown is lossy. Replaces the whole document, drops anything Markdown cannot represent. No prompt, matching JSON update.
  • No conflict detection. document_revision is returned but not enforced on any write path.
  • No targeted edits. update replaces, edit appends; no way to change one section in place.
  • --output and agent mode do nothing under --markdown, matching skills remote get.

@andyjmorgan
andyjmorgan requested a review from a team as a code owner August 21, 2026 14:37
@andyjmorgan
andyjmorgan force-pushed the feat/notebooks-markdown branch from bd17bdb to 691559e Compare August 21, 2026 14:55
@andyjmorgan
andyjmorgan marked this pull request as draft August 21, 2026 15:45
Work with a notebook as a Markdown document instead of a JSON cells
array. These call /api/unstable/notebooks, which the notebooks team has
not promoted to /api/v2 yet, so the flag is documented as experimental.

- get --markdown prints the document; create/update take a Markdown file
- edit --markdown appends server-side via the content-fragment endpoint,
  so the rest of the document is not rewritten
- Reject --jq alongside --markdown, and reject JSON files passed with
  --markdown before any request is made
- Translate the backend's 5xx for notebooks that have no Markdown
  projection into an actionable message

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@andyjmorgan
andyjmorgan force-pushed the feat/notebooks-markdown branch from 691559e to 770bc32 Compare August 21, 2026 15:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant