Skip to content
GitLab
Next
Closed
Issue created by Michael Le@mleDeveloper

Editing frontmatter in the static site editor

Problem to solve

Defined at the top of each file, front matter is a powerful and flexible pattern for defining page-specific variables and meta data in a statically generated site. However, because the front matter is included with the body of the content, it can be confusing to users unfamiliar with the pattern. Whether it's defined as YAML or JSON, the front matter requires consistent and accurate syntax. A missed colon or an invalid property can cause the entire site to fail to build.

The Static Site Editor offers a visual editing experience for the Markdown content, but specifically filters out the front matter to prevent unintentional edits or formatting errors. Users need a way to safely and confidently edit and inspect front matter from within the Static Site Editor.

Intended users

User experience goal

A user should be able to view the front matter and edit it without switching to the raw Markdown source in the Static Site Editor.

Proposal

  • A user will not see any front matter in the WYSIWYG or raw Markdown mode
    • Note: this is a change from the current implementation, which exposes the front matter in Markdown mode.
  • Before loading the page in the Static Site Editor, the front matter is parsed and removed from the editor.
  • 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 front matter. These can be addressed in future issues.

Further details

  1. 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.
  2. Front matter should be edited using a text field with the key as the label and the value as the field input text.
  3. Arrays could be handled as comma separated lists in a text field
  4. 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.
  5. 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.

Middleman supports both YAML and JSON front matter. The GitLab Handbook exclusively uses YAML, but since we included the editor as part of a Middleman project template we should ensure JSON front matter is parsed as well.

Documentation

Availability & Testing

What does success look like, and how can we measure that?

Acceptance criteria

  1. A user can see the values of all metadata defined in the file's front matter
  2. A user can edit all values in the file's front matter
  3. No front matter is displayed in the markdown editor

Links / references

Edited by Michael Le