kemayo
commented
7 months ago Separately, it might be wise to clarify where the character offsets used in the ranges start in a document using YAML front-matter. I'm assuming that it's intended that position 0 is at the start of the front-matter, but it wouldn't be inherently unreasonable to say it should be at the start of the document text after the front-matter...
EDIT: I opened #5 to mostly incorporate this concern.
I'm not really a fan of how this makes hand-editing these Markdown files basically impossible without invalidating the annotations. As-written, the only change that you could make to a document that contains these annotations which wouldn't require a massive amount of updating range-offsets by hand would be appending text after the end of the annotation range.
I'd like to suggest a small change that makes it potentially simpler for people to edit files containing these annotations: specify that character ranges for author annotation values are relative to the hash annotation's starting location. (It's possible that you already intend this, but the spec is silent on the topic, and there's no examples given of a document which isn't completely covered by the hash annotation range.)
This would still require someone prepending content before the annotated range to go in and update the hash annotation's starting location, but that's a single change that's pretty simple, rather than requiring every single specified range to be updated.
(Editing the annotated text itself without a dedicated tool is obviously inherently very difficult, given the requirements to both update the offsets and then hash the contents, which I'd say is outside the scope of this issue. Making it simpler to treat it as a read-only block from a normal editor would be useful, however.)