Text: Support Frontmatter in MD files

[paulhibbitts]

Is your feature request related to a problem? Please describe.
I'd love to use the Collaborative editor to share Page files for the Grav CMS (a flat-file CMS). Right now any Frontmatter (https://jekyllrb.com/docs/front-matter/) originally in the file seems to be re-saved in a different format. Frontmatter is used quite widely in both static site generators and flat-file CMSs.

Here is a simple example of Frontmatter for testing purposes:

title: 'Classic Modern Architecture'
date: '17:34 06/27/2017'
---

Here is the main content area of the MD file.

When saved, this is the result:

title: 'Classic Modern Architecture' date: '17:34 06/27/2017'

Here is the main content area of the MD file.

Describe the solution you'd like
Any frontmatter contained in a MD should be visually distinct from the main content of the MD file, and also be editable (like a Code Block perhaps?)

Describe alternatives you've considered
I've not been able to find any so far.

Additional context
Add any other context or screenshots about the feature request here.

Thanks very much! The new collaborative editor is awesome to see in Nextcloud!

[juliushaertl]

Thanks for your suggestion. While front matter is not really specified in commonmark, I still agree that we should make sure that it is not changed. So we should make sure to strip it from the markdown parsing and add a simple code block for editing at the beginning of the document.

[paulhibbitts]

That sounds great @juliushaertl , thank you for considering this suggestion.

[brainchild0]

You could also consider rendering the displayable content, such as title, in appropriate styles. But somehow the user would need to able to add or to edit the other fields.

Also, not sure, but if the block is appearing disassembled after changes are saved, then maybe there is a separate issue with the way documents are processed. A MarkDown editor ideally should, I think, preserve as much literal content as possible from the original document, not attempt to produce an entirely new document from the logical features of the AST.

[hugoroy]

Hi, I think this feature is definitely important :-)

But I don't think it should be rendered as text like the rest. These blocks are supposed to be metadata (see, e.g. https://pandoc.org/MANUAL.html#extension-yaml_metadata_block which specifies it cleary, or https://jekyllrb.com/docs/front-matter/ which specifies it implicitly with the special rules IMO). The point is: you can have a lot more metadata in these blocks, not just "title" and "author" (I use them extensively to process with Pandoc). Trying to use them to render anything will probably lead to a lot of chaos…

So it probably requires a lot of work to get right from the UI/UX perspectives (the simple solution could be to treat it like a codeblock - but instead of inserting the codeblocks delimiter, use "---" and "---"; but this does not feel very satisfactory…)

[brainchild0]

But I don't think it should be rendered as text like the rest. These blocks are supposed to be metadata.

The point is: you can have a lot more metadata in these blocks, not just "title" and "author

The suggestion is not to render all metadata as stylized text, only the elements that appear visually in the document, such as title and author.

Naturally, other data must be shown in another manner. A collapsible code block would allow easy editing, while still offering a distraction-free view of the document that resembles final output with respect to display of the title and similar fields.

[dyamon]

I saw the issue and since this is something I'm quite interested in, I tried to sketch something. The first attempt is to use a foldable table layout

Folded:

Unfolded:

And following @brainchild0 suggestion, a version with some of the metadata rendered differently

Folded:

Unfolded:

I don't feel like this solution is intrusive w.r.t. to the goal of keeping Text distraction free. Let me know what you think!

Still, I have no experience with the code base and I have close to 0 knowledge of JS, so I don't know if this is even feasible.

That said I think simply fixing the formatting bug that breaks the yaml frontmatter should be enough for now, and having the yaml block printed verbatim at the beginning of the file is a "good enough" solution, that allows the use of Text with CMSs like PicoCMS.

[juliushaertl]

@dyamon Thanks a lot for the mockups, this looks great imo but let's bring @nextcloud/designers in here for some additional feedback.

Regarding the implementation, we probably need to implement our own frontmatter plugin for markdown it that then returns a node that can be parsed by tiptap. It could be based on https://www.npmjs.com/package/markdown-it-front-matter

[skjnldsv]

Looks cool to me too :)

[paulhibbitts]

Thanks very much for putting that together @dyamon , I guess the question is how frequently would users want to edit Frontmatter? I like the idea of making it less visible for users wanting to focus on actual Markdown content etc. Might "Frontmatter" be a more expected term in this context (vs. Metadata)?

[dyamon]

I guess the question is how frequently would users want to edit Frontmatter?

You are right, in my head the foldable section would appear only if the user inserts an opening and closing --- (or a closing ...) at the beginning of the file.

To put it even more "out of the way" for the user, the menu bar might be a better choice. Something like this maybe?

Might "Frontmatter" be a more expected term in this context (vs. Metadata)?

Yes definitely, I originally put "Metadata" as a (possibly more user-friendly?) placeholder. I guess the discussion is the same in the menu bar example regarding which icon to use to indicate "Frontmatter"

[brainchild0]

I like visual representations submitted by @dyamon.

I make a few comments:

1. I most like the final image, which invokes my earlier suggestion of a formatted display of relevant fields.
2. If the metadata are shown in a table format, I would suggest distinctive formatting, such as shading behind the text or along the margin.
3. The representations provided are not distracting, but I would personally favor a version of the collapsed representation that does not add vertical spacing. Possibilities include a simple, small arrow, without the word metadata, just above the body text, or the collapsed representation being located in the margin, outside the region used by the body text.
4. Many metadata blocks will be simple, flat tables, but MarkDown processing applications support metadata with complex formatting that includes nested tables and lists. Further, YAML is a detailed standard, and many features rarely used by end users must still be handled by conformant processors according to specification. These considerations point to the need, at least in some cases, for editing of the YAML data as plain text.

---

Might "Frontmatter" be a more expected term in this context (vs. Metadata)?

Yes definitely, I originally put "Metadata" as a (possibly more user-friendly?) placeholder. I guess the discussion is the same in the menu bar example regarding which icon to use to indicate "Frontmatter"

I would understand frontmatter to be an informal synonym, in this context, by analogy to book publishing, to the more precise term metadata. If not, the distinction needs to be clarified.

[nathanlesage]

Thank you for considering this! In fact, I had one file completely ripped apart due to this (P.S.: I think, https://github.com/nextcloud/text/issues/593 is related). While I certainly like the looks of the new editor, this is definitely a deal breaker, as I would like to emphasise that indeed frontmatters are quite common among Markdown editors. In fact I don't know any (Desktop) app that does _not_ support frontmatters.

Furthermore, I think a simple non-parsing codeblock at the top would be quite sufficient, especially if it takes more resources to render the frontmatter nicely (which would be a cool addendum). Because the fact that it should not break it is definitely _much_ more important.

[paulhibbitts]

Any updates on this possible enhancement @juliushaertl ? This would really widen the uses of the Collaborative editor ,and I am really jazzed about using it along with Grav CMS!

It also looks like others are trying to edit Markdown files with Frontmatter with the new editor:
https://twitter.com/zettlr/status/1225449750411010048

[ghost]

I can confirm that @paulhibbitts idea is great! Page-sync with external storage works seamlessly with grav cms so having the frontmatter issue solved would be awesome, because right now pages look like this if you do it :). So having the frontmatter being interpreted correctly would be a really awesome solution.

[jancborchardt]

Agreed, @dyamon’s mockups are very nice! :)

Since we always do it step-by-step, some considerations:

1. We should first start as @juliushaertl mentioned and simply exclude the Frontmatter part to not mess that up. That is, still displaying it to be edited.
2. When that works reliably, we can look into collapsing it. In-place seems best, as the tag/metadata icon in the heading might be missed. And especially when you _do_ use these tags, they should be visible.
3. Then we can check to work on a table-based representation of the content. :)

[mcnesium]

Just pointing out that there are similar issues elsewhere with suggestions to integrate existing third-party modules, which might be worth to take a look at…

[brainchild0]

I think that overall the stepwise approach proposed by @jancborchardt is very sound.

I make a few slight comments:

• Perhaps it is best to stay open to the possibility of one or two additional further steps, which might include formatting the title information such as it might appear in a published representation.
• The metadata block would not in all cases consist of a table with only primitive values, but rather might include values of arbitrarily nested structures such as lists and further tables. It is important to have a sense of how data from the general YAML data model might be displayed and might be edited in each stage such as to preserve optimal usability and to minimize destructive effects for editing documents from other sources.
• Perhaps approaches other than inline folding would be more aligned to the WYSYG spirit. As the word _metadata_ appearing inline is not included in what you get, perhaps it equally ought not to be included in what you see. A button with a popup window might be a more suitable metaphor, and I personally have yet to be persuaded by any objections offered against this approach.

[basebuilder]

This is a very cool and needed addition to the text editor tool!

Are any of you familiar with Netlify CMS? It's a lightweight GUI that works on top of multiple static-site platforms by simply specifying config.yaml and then it renders various form fields like:

In addition to the nice collapsible rendering by @dyamon perhaps the text editor could also borrow inspiration here and offer form fields to edit the values:

title --> text input 
date --> date picker
lang --> dropdown
ingredients --> tokenized elements in text input

If anyone wants to work on this, has some available time,and needs a small budget to work with- I am part of a collective that allocates funding to open source projects that we use. We would be happy to explore funding some dev help on this issue, read more here.