Flexible PATCH

This was released as part of release 3.0 of this extension. See Changes to PATCH requests between versions 2.0 and 3.0 for more information.

Current API

The current PATCH API supports positioning content relative only to a known Heading, and also only supports appending content.

When targeting a "Heading", the zone between the target heading and the next heading of the same level (or the end of the document) is considered your "target", and your insertion position controls whether you insert content immediately below the heading, or immediately above the end of your target zone.

Heading-relative

• Important
  • Heading (string): Which heading to insert content into?
  • Content-Insertion-Position ('end' | 'beginning'): Position content at end of heading block or beginning.
• Options
  • Content-Insertion-Ignore-Newline (true | false): Insert content before or after any newlines in the header block.
  • Heading-Boundary (string): When targeting a nested header, use this as the boundary between these heading names specified in Heading.

Possible Future API

The new API will be able to append or replace content in an identified target.

• Target-Type ('heading' | 'block' | 'frontmatter')
• Action ('prepend' | 'replace' | 'append')
• Target (string):
  • For heading: The name of the heading to use as our target.
  • For block: The ID of the block to use as our target.
  • For frontmatter: The name of the frontmatter field to use as our target.
• Target-Encoding (undefined (default) | 'base64'):
  • There may be better encodings than base64, possibly? Maybe we could instead just use URL-encoding, and make it always interpreted as such?
  • Not all languages only use ASCII characters -- for those languages, we will need to encode their UTF-8 bytes with base64 to use them in a header.

& will have some optional fields:

• Target-Delimiter (string): Used for exactly the same thing that Heading-Boundary was used for above.

Problems to think through

• How to handle situations like setting the current scroll position (see #75). Maybe editor state fields could just be a new Target-Type (maybe 'editor')?
• What are the functions of prepend and append in frontmatter? Does that change between when the data type found there is a string or a list?
• Does it make sense that the zone you target when using heading does not include the heading itself (and instead starts immediately afterward)? If so: would the block ID referenced when using block also not be included in the "zone"?
• How does leading and trailing newlines interact with this? Do we need to handle it in any special way? Maybe we need an option to either configure this to ignore it?
• How can we make it possible for you to use a non-ASCII value as a Target? HTTP Headers can have only ASCII characters; so we'll need to allow for some way of encoding non-ASCII characters so you can target headings that are written in languages like Russian, Arabic, or Chinese.