GitLab Next

Problem to solve

Front matter is included at the beginning of a markdown file to provide the static site generator the necessary metadata to format, configure, or parse the page. This content, however, isn't frequently edited after initial creation and becomes a bit of a liability when presented alongside the rest of the page content. If a user unfamiliar with the very specific formatting and available options for any given front matter value attempts to edit it (or accidentally edits it) the entire page could fail to render.

Users of the Static Site Editor should feel confident that the changes they make to the page will not break formatting.

Intended users

• Parker (Product Manager)
• Presley (Product Designer)

User experience goal

The user should not see any YAML front matter when editing a page in the WYSIWYG mode of the Static Site Editor. Users can still make critical front matter edits in the Markdown editing mode.

Proposal

We should hide or otherwise ignore the front matter in the file when displaying content in the WYSIWYG mode of the editor. The content should not actually be removed from the file, since we want that data to remain after the user submits changes and we still want it to appear in the Markdown editing mode.

Further details

In another issue, we'll use the front matter data to present the properties as form fields. So it's important that we are actually parsing the data, not just throwing it out.

Documentation

Availability & Testing

Design

Frontmatter in Markdown only

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

Acceptance criteria

1. A user does not see any front matter in the WYSIWYG or raw Markdown areas of the Static Site Editor

Tasks

We will be taking the pre-parse approach as referenced here

• v1 - regexp solution as v1 where v2 = more research time in combo w/first-class editing components with frontmatter
  • MR1 - create wrapper service (frontmatterParser?) solution (3rd party or custom for future-proofing swapability)
    • consume source and forward unparsed (prep for MR2)
  • [-] MR2 - create contentModel = { header: 'frontmatter-literal-here', body: 'remaining source' } and use in service
    • WYSIWYG content via body (consider piping through other parsers in design, likely YAGNI but can envision this)
    • [-] Markdown content via computed of header & body
    • [-] Still forward unparsed (prep for MR3)
  • MR2 - sync above w/component
    • Likely need to tap into mode event changes
    • Ensure editing works as expected
• v2 - 3rd party frontmatter parse solution if needed (grey-matter?)