Edit front matter in the Static Site Editor
Problem to solve
When the front matter is included with the body of the content, it is more likely to confuse users unfamiliar with they purpose or syntax of the metadata. Users need a way to safely and confidently edit and inspect front matter included in a file from within the Static Site Editor.
Intended users
User experience goal
A user should be able to view the front matter and edit it outside of the primary editing experience.
Proposal
- A user will not see any front matter in the main editor, either in WYSIWYG or raw Markdown mode
- If available, a separate area of the Static Site Editor will contain all the front matter variable, displayed as form fields
- A user can view these "settings" and edit them as needed
- Saving changes to the file will apply the changes to the front matter along with any changes made in the markdown editor
Validation and Linting of Frontmatter
This list is a placeholder for known and common issues which cause invalid frontmatter. These can be addressed in future issues.
- No space after comma (gitlab-com/www-gitlab-com!57789 (comment 386588643))
- Wrong number of dashes in beginning or ending delimiter
- Ensure colon key/value delimiter (assuming a colon is always expected)
Further details
- This iteration is focused on making all front matter editable. We will eventually allow for more configuration of the front matter fields, but for now we should treat all properties in the same way.
- Front matter should be edited using a text field with the key as the label and the value as the field input text.
- Arrays should be handled as comma separated lists in a text field
- No validation of the form input is needed in this iteration, acknowledging that invalid input will break the format of the page or prevent the build from succeeding.
- If possible, we should title-case the keys when creating the form fields. The YAML is likely
Example:
---
title: Homepage
---
becomes a form field with the label reading Title
and with the value of Homepage
pre-filled.
Documentation
Availability & Testing
What does success look like, and how can we measure that?
Acceptance criteria
- A user can see the values of all metadata defined in the file's front matter
- A user can edit all values in the file's front matter
- No front matter is displayed in the markdown editor
Links / references
- Take note that Toast UI commented about handling frontmatter and I recently asked for an update: https://github.com/nhn/tui.editor/issues/998#issuecomment-668036601
Edited by Derek Knox