Thinkmill / Thinkmill/keystatic

[Markdoc field] Writing an unrecognized tag makes the entry uneditable [Error: document has unexpected children]

Open
#1,428 1 comment 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
2.4k
Forks
159
Avg merge
21h 41m
Merged PRs (30d)
2

Description


TL;DR: Being able to edit the raw file content from the CMS would solve a lot of issues.


Nothing prevents us to write a custom tag inside a Markdoc field, which arguably is a good thing! Except when we save the document and it errors out and becomes uneditable with the following error.

Unexpected error: Error: undefined:document has unexpected children

In my opinion, two features should be added to handle this gracefully. And even before that, only the corresponding field should display an error and not the whole document... And there should be a validation step preventing us from saving... But I guess this is planned already so I'll skip to improvement proposals.

1. The raw editing view

Make the current file and/or at least the document-like fields editable as raw content from the CMS. Of course we can edit the document manually from the cloned repo locally or even from Github but the goal of the CMS is to avoid that. If the team needs more arguments to be convinced, just tell me. For now I'll stop there assuming this is the obvious direction the project is taking.

Note that IMO implementing a raw file editing experience would (temporarily) "fix" a whole lot of issues allowing us to work around bugs or lacking features, especially while the project matures!

Feature wise, we could have a toggle to switch between the normal view and the "raw view". The raw view would display the whole content of the file in a "code friendly" editable area (ideally with code highlighting).

UI wise, the toggle could be an icon at the top, near the "save" button.

Bonus idea: Why not use this toggle to allow users to switch between different entryLayout options by themselves. I would love to be able to switch between "form" and "content" from the CMS. And we could add "raw" as a third option.

Please tell me if I should open another issue to focus on this feature request.

2. Loosen the strictness of the content allowed in document-like fields

Maybe have a strict flag we can turn off somewhere in the field config to not error out on unknown tags and simply display them as text when the engine encounters one then.

When I encountered this issue, my first instinct was to look for a way to use the fields.ignored on my tag name but I don't think this is possible on components (?). And anyway, it would still be a half solution.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reproducing the error in a Markdoc field after saving an unrecognized tag, then trace how the CMS handles document-like fields and the entryLayout options. Compare the proposed raw editing view, field-level validation, and configurable strictness; done would require a decided scope and agreed behavior for invalid or unknown tags.

Written by the indexing model from the issue text.

Assessment

Tech stack
markdown, typescript
Domain
content, frontend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.