Comments file format

File name

The Markdown file name plus .meta: launch-plan.md gets launch-plan.md.meta. The file exists only while there is at least one comment.

Example

{
  "format": "markko-comments",
  "version": 1,
  "document": "launch-plan.md",
  "comments": [
    {
      "id": "c1",
      "anchor": {
        "quote": "300 ms",
        "prefix": "in less than ",
        "suffix": ".",
        "heading": "Goals"
      },
      "author": {
        "name": "Andreas",
        "kind": "person"
      },
      "created": "2026-10-10T07:41:00+02:00",
      "resolved": false,
      "body": "Cold or warm start?",
      "replies": [
        {
          "author": {
            "name": "Planning agent",
            "kind": "agent"
          },
          "created": "2026-10-10T08:02:00+02:00",
          "body": "Warm start."
        }
      ]
    }
  ]
}

Fields

• anchor: the quoted text, some characters before and after it, and the nearest heading. Markko uses them to find the passage again after the file changed.
• author.kind: person or agent.
• resolved: true when the comment is done.
• replies: a flat list, one level deep.

Writing the file

Keep the ids of existing comments. Markko merges by id, so a reply written by a script is kept when you edit comments at the same time.