feat(core): add default markdown behaviors to PTE #8168

christianhg · 2025-01-03T13:38:11Z

Description

This change extends the core behaviors of PTE with default markdown behaviors for a more pleasant writing experience. This allows you to:

Use # characters to create headings
Use > to create a blockquote
Use Backspace at the beginning of block to clear its style
Use -, *, _ or 1. to initiate a list

This is achieved by providing the behaviors configuration for PTE where the coreBehaviors are first spread into the array (to preserve core behaviors) and the additional markdown behaviors are added afterwards. The markdown behaviors require us to define what styles to use, and here we just default to the most common names for these. Later, we can figure out how to allow you to configure markdown behaviors through the Schema, but for now these sensible defaults are hard-coded.

The only downsides here is that:

You can't opt out of markdown behaviors if you for some reason don't like them
You can't change the configuration if for example your lists are named something else
Things could potentially get confusing if you use unconventional names for styles and lists, for example if h1 means something completely different in your context.

These are downsides we'll have to live with for now.

What to review

Test the new writing experience and see if you like it!

Testing

These markdown behaviors are already used in Create and are backed by automatic tests in the PTE repo: https://github.com/portabletext/editor/blob/main/packages/editor/gherkin-spec/behavior.markdown.feature

Notes for release

The Portable Text Editor now ships with markdown keyboard shortcuts for headings, block quotes and lists

This change extends the core behaviors of PTE with default markdown behaviors for a more pleasant writing experience. This allows you to: 1. Use `#` characters to create headings 2. Use `>` to create a blockquote 3. Use `Backspace` at the beginning of block to clear its style 4. Use `-`, `*`, `_` or `1.` to initiate a list This is achieved by providing the `behaviors` configuration for PTE where the `coreBehaviors` are first spread into the array (to preserve core behaviors) and the additional markdown behaviors are added afterwards. The markdown behaviors require us to define what styles to use, and here we just default to the most common names for these. Later, we can figure out how to allow you to configure markdown behaviors through the Schema, but for now these sensible defaults are hard-coded. The only downsides here is that: 1. You can't opt out of markdown behaviors if you for some reason don't like them 2. You can't change the configuration if for example your lists are named something else 3. Things could potentially get confusing if you use unconventional names for styles and lists, for example if `h1` means something completely different in your context. These are downsides we'll have to live with for now.

vercel · 2025-01-03T13:38:16Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
page-building-studio	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jan 3, 2025 1:52pm
performance-studio	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jan 3, 2025 1:52pm
test-next-studio	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jan 3, 2025 1:52pm
test-studio	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jan 3, 2025 1:52pm

1 Skipped Deployment

Name	Status	Preview	Comments	Updated (UTC)
studio-workshop	⬜️ Ignored (Inspect)	Visit Preview		Jan 3, 2025 1:52pm

EoinFalconer

LGTM!! ✨

github-actions · 2025-01-03T13:43:34Z

No changes to documentation

github-actions · 2025-01-03T13:49:30Z

Component Testing Report Updated Jan 3, 2025 1:49 PM (UTC)

❌ Failed Tests (1) -- expand for details

File	Status	Duration	Passed	Skipped	Failed
comments/CommentInput.spec.tsx	✅ Passed (Inspect)	1m 3s	15	0	0
formBuilder/ArrayInput.spec.tsx	✅ Passed (Inspect)	12s	3	0	0
formBuilder/inputs/PortableText/Annotations.spec.tsx	❌ Failed (Inspect)	1m 19s	5	0	1
formBuilder/inputs/PortableText/copyPaste/CopyPaste.spec.tsx	✅ Passed (Inspect)	50s	11	7	0
formBuilder/inputs/PortableText/copyPaste/CopyPasteFields.spec.tsx	✅ Passed (Inspect)	0s	0	12	0
formBuilder/inputs/PortableText/Decorators.spec.tsx	✅ Passed (Inspect)	25s	6	0	0
formBuilder/inputs/PortableText/DisableFocusAndUnset.spec.tsx	✅ Passed (Inspect)	14s	3	0	0
formBuilder/inputs/PortableText/DragAndDrop.spec.tsx	✅ Passed (Inspect)	26s	6	0	0
formBuilder/inputs/PortableText/FocusTracking.spec.tsx	✅ Passed (Inspect)	1m 6s	15	0	0
formBuilder/inputs/PortableText/Input.spec.tsx	✅ Passed (Inspect)	1m 26s	21	0	0
formBuilder/inputs/PortableText/ObjectBlock.spec.tsx	✅ Passed (Inspect)	1m 39s	18	0	0
formBuilder/inputs/PortableText/PresenceCursors.spec.tsx	✅ Passed (Inspect)	13s	3	9	0
formBuilder/inputs/PortableText/Styles.spec.tsx	✅ Passed (Inspect)	26s	6	0	0
formBuilder/inputs/PortableText/Toolbar.spec.tsx	✅ Passed (Inspect)	1m 43s	21	0	0
formBuilder/tree-editing/TreeEditing.spec.tsx	✅ Passed (Inspect)	0s	0	3	0
formBuilder/tree-editing/TreeEditingNestedObjects.spec.tsx	✅ Passed (Inspect)	0s	0	3	0

github-actions · 2025-01-03T13:50:32Z

⚡️ Editor Performance Report

Updated Fri, 03 Jan 2025 13:50:31 GMT

Benchmark	reference ^{latency of sanity@latest}	experiment ^{latency of this branch}	Δ (%) ^{latency difference}
article (title)	24.4 efps (41ms)	25.0 efps (40ms)	-1ms (-2.4%)	✅
article (body)	48.1 efps (21ms)	63.7 efps (16ms)	-5ms (-24.5%)	✅
article (string inside object)	27.4 efps (37ms)	26.7 efps (38ms)	+1ms (+2.7%)	✅
article (string inside array)	23.3 efps (43ms)	25.0 efps (40ms)	-3ms (-7.0%)	✅
recipe (name)	52.6 efps (19ms)	58.8 efps (17ms)	-2ms (-10.5%)	✅
recipe (description)	58.8 efps (17ms)	66.7 efps (15ms)	-2ms (-11.8%)	✅
recipe (instructions)	99.9+ efps (6ms)	99.9+ efps (5ms)	-1ms (-/-%)	✅
synthetic (title)	19.2 efps (52ms)	20.0 efps (50ms)	-2ms (-3.8%)	✅
synthetic (string inside object)	19.4 efps (52ms)	19.2 efps (52ms)	+1ms (+1.0%)	✅

efps — editor "frames per second". The number of updates assumed to be possible within a second.

Derived from input latency. efps = 1000 / input_latency

Detailed information

🏠 Reference result

The performance result of sanity@latest

Benchmark	latency	p75	p90	p99	blocking time	test duration
article (title)	41ms	59ms	77ms	447ms	857ms	10.6s
article (body)	21ms	24ms	45ms	84ms	205ms	5.9s
article (string inside object)	37ms	39ms	44ms	166ms	291ms	6.9s
article (string inside array)	43ms	46ms	50ms	78ms	241ms	7.2s
recipe (name)	19ms	21ms	27ms	64ms	5ms	7.0s
recipe (description)	17ms	19ms	21ms	37ms	0ms	4.4s
recipe (instructions)	6ms	8ms	11ms	14ms	0ms	3.1s
synthetic (title)	52ms	56ms	62ms	119ms	590ms	14.3s
synthetic (string inside object)	52ms	55ms	59ms	108ms	488ms	8.2s

🧪 Experiment result

The performance result of this branch

Benchmark	latency	p75	p90	p99	blocking time	test duration
article (title)	40ms	47ms	69ms	457ms	732ms	10.3s
article (body)	16ms	18ms	24ms	186ms	246ms	5.4s
article (string inside object)	38ms	41ms	48ms	81ms	250ms	6.7s
article (string inside array)	40ms	44ms	48ms	71ms	129ms	6.7s
recipe (name)	17ms	18ms	20ms	38ms	0ms	6.5s
recipe (description)	15ms	17ms	19ms	33ms	0ms	4.3s
recipe (instructions)	5ms	7ms	9ms	28ms	0ms	3.0s
synthetic (title)	50ms	52ms	56ms	116ms	181ms	11.5s
synthetic (string inside object)	52ms	57ms	68ms	566ms	1103ms	8.4s

📚 Glossary

column definitions

benchmark — the name of the test, e.g. "article", followed by the label of the field being measured, e.g. "(title)".

latency — the time between when a key was pressed and when it was rendered. derived from a set of samples. the median (p50) is shown to show the most common latency.

p75 — the 75th percentile of the input latency in the test run. 75% of the sampled inputs in this benchmark were processed faster than this value. this provides insight into the upper range of typical performance.

p90 — the 90th percentile of the input latency in the test run. 90% of the sampled inputs were faster than this. this metric helps identify slower interactions that occurred less frequently during the benchmark.

p99 — the 99th percentile of the input latency in the test run. only 1% of sampled inputs were slower than this. this represents the worst-case scenarios encountered during the benchmark, useful for identifying potential performance outliers.

blocking time — the total time during which the main thread was blocked, preventing user input and UI updates. this metric helps identify performance bottlenecks that may cause the interface to feel unresponsive.

test duration — how long the test run took to complete.

pedrobonamin

Yesss! Finally!
Do you have a follow up ticket to allow users to customize this through the schema? It would be great to support that

Thanks for building this!

christianhg · 2025-01-03T15:31:32Z

Yesss! Finally! Do you have a follow up ticket to allow users to customize this through the schema? It would be great to support that

We don't. But we should! We definitely want to support this in the future.

Thanks for building this!

Thank you 🙇

christianhg requested a review from a team as a code owner January 3, 2025 13:38

christianhg requested review from cngonzalez and removed request for a team January 3, 2025 13:38

EoinFalconer approved these changes Jan 3, 2025

View reviewed changes

vercel bot deployed to Preview – page-building-studio January 3, 2025 13:45 View deployment

vercel bot deployed to Preview – performance-studio January 3, 2025 13:45 View deployment

vercel bot deployed to Preview – test-studio January 3, 2025 13:47 View deployment

pedrobonamin approved these changes Jan 3, 2025

View reviewed changes

vercel bot deployed to Preview – test-next-studio January 3, 2025 13:52 View deployment

christianhg added this pull request to the merge queue Jan 6, 2025

Merged via the queue into next with commit 17aa32c Jan 6, 2025
57 checks passed

christianhg deleted the feat-pte-markdown-behaviors branch January 6, 2025 07:23

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(core): add default markdown behaviors to PTE #8168

feat(core): add default markdown behaviors to PTE #8168

christianhg commented Jan 3, 2025

vercel bot commented Jan 3, 2025 •

edited

Loading

EoinFalconer left a comment

github-actions bot commented Jan 3, 2025

github-actions bot commented Jan 3, 2025

github-actions bot commented Jan 3, 2025

🏠 Reference result

🧪 Experiment result

📚 Glossary

column definitions

pedrobonamin left a comment

christianhg commented Jan 3, 2025

feat(core): add default markdown behaviors to PTE #8168

feat(core): add default markdown behaviors to PTE #8168

Conversation

christianhg commented Jan 3, 2025

Description

What to review

Testing

Notes for release

vercel bot commented Jan 3, 2025 • edited Loading

EoinFalconer left a comment

Choose a reason for hiding this comment

github-actions bot commented Jan 3, 2025

github-actions bot commented Jan 3, 2025

github-actions bot commented Jan 3, 2025

⚡️ Editor Performance Report

🏠 Reference result

🧪 Experiment result

📚 Glossary

column definitions

pedrobonamin left a comment

Choose a reason for hiding this comment

christianhg commented Jan 3, 2025

vercel bot commented Jan 3, 2025 •

edited

Loading