Proposal: Feature: Markdown preview for markdown-supported fields #260

Francesco Bellini · 2024-10-04T02:42:16+02:00

Francesco Bellini commented

2024-10-04 02:42:16 +02:00

Overview

To succeed in writing markdown for descriptions, release notes, review comments, can be challenging from the textarea, without a reference.
While in description and changelogs we are able to amend the errors or adjust the markdown by updating, in comments it's not possible (at least for now, afaik).

In either case, having a quick preview of the markdown would be useful to prevent useless updates or bad-format comments. Also, after approval, editing descriptions creates review comments, which is not optimal in case of multiple simple markdown/typos fix edits which could be avoided with a better look.

My Proposal

Screenshots avaliable; scroll down

Use a [Gitea, GitHub, etc]-like tabs system for markdown preview (like in this page comments). A classic.
A couple of tabs on top of the textarea: Write | Preview ; using styling that fits the platform.
A very minimal API to process the input text using the same render() function used by the |markdown pipe from templates.
JS script to handle tabs switch and markdown fetch, client-side
The script also takes care of the following cases:
- If the trimmed text is empty, no call is made, and an empty-case message shows (low opacity)
- If the text is the same as the last fetch, no call is made (and the result is kept)
- When a fetch starts, in the meantime, a loading text shows (low opacity), in case of slow connection or slow response for any reason
- If the fetch goes wrong, for whatever reason, a generic error message shows (low opacity)
I tried to optimize the number of calls as much as possible.
Previews are fetched only on-demand, and empty-like and unchanged cases are covered.

In a normal case, the API should respond in a blink.

More details

To recognize markdown fields from field.html template, I created a simple filter is_markdown_field, to check if the field.name matches one of the markdown fields.

Note

While testing, I noticed that user-review comments supports markdown without having the help_text, so users may not be aware.
Because of that, as of now, i did not included that field name.

The help_text could be provided to the user-review field in order to inform users about the markdown support. Or markdown shoudn't be supported in that field.

The id of the new elements involved use as a suffix the field.name. This way, multiple textareas on the same page, are handled independently by the script (like in the post-upload page, with description and first changelog on the screen)

Styling:
To be consistent, tabs use the hero-tabs and is-active classes and HTML structure.
This matches the style of the tab-bars on the platform.
I used the generic class style-rich-text, like extensions description, which seems to work fine, even though various markdown elements (comments, changelog) uses different classes structure, but the result seems to look the same.

Images of the result

Description:

Approval-queue comments:

Release notes:

Style match:

A mention of markdown preview is made in infrastructure/extensions-website#243.

I'm available for any kind of changes that might be necessary. From my testing, everything looks good!
I wasn't familiar with the Django framework and I'm pretty new to this project, so I tried to look around and search in order to try to blend well in the code.

### Overview To succeed in writing markdown for descriptions, release notes, review comments, can be challenging from the textarea, without a reference. While in description and changelogs we are able to amend the errors or adjust the markdown by updating, in comments it's not possible (at least for now, afaik). In either case, having a **quick preview of the markdown** would be useful to prevent useless updates or bad-format comments. Also, after approval, editing descriptions creates review comments, which is not optimal in case of multiple simple markdown/typos fix edits which could be avoided with a better look. --- ### My Proposal _Screenshots avaliable; scroll down_ 1) Use a [Gitea, GitHub, etc]-like tabs system for markdown preview (like in this page comments). A classic. _A couple of tabs on top of the textarea: **Write** | **Preview** ; using styling that fits the platform._ 2) A very minimal API to process the input text using the same `render()` function used by the `|markdown` pipe from templates. 3) JS script to handle tabs switch and markdown fetch, client-side _The script also takes care of the following cases:_ - If the trimmed text is empty, no call is made, and an empty-case message shows (low opacity) - If the text is the same as the last fetch, no call is made (and the result is kept) - When a fetch starts, in the meantime, a loading text shows (low opacity), in case of slow connection or slow response for any reason - If the fetch goes wrong, for whatever reason, a generic error message shows (low opacity) > _I tried to optimize the number of calls as much as possible._ > _Previews are fetched only on-demand, and empty-like and unchanged cases are covered._ _In a normal case, the API should respond in a blink._ --- #### More details *To recognize markdown fields from `field.html` template, I created a simple filter `is_markdown_field`, to check if the `field.name` matches one of the markdown fields.* > **Note** > While testing, I noticed that user-review comments supports markdown without having the help_text, so users may not be aware. > Because of that, as of now, i did not included that field name. > > The `help_text` could be provided to the user-review field in order to inform users about the markdown support. Or markdown shoudn't be supported in that field. --- The id of the new elements involved use as a suffix the `field.name`. This way, multiple textareas on the same page, are handled independently by the script (like in the post-upload page, with description and first changelog on the screen) --- **Styling**: To be consistent, tabs use the `hero-tabs` and `is-active` classes and HTML structure. This matches the style of the tab-bars on the platform. I used the generic class `style-rich-text`, like extensions description, which seems to work fine, even though various markdown elements (comments, changelog) uses different classes structure, but the result seems to look the same. --- ## Images of the result ### Description: ![immagine](https://projects.blender.org/Francesco-Bellini/extensions-website/pulls/1/attachments/f79a0546-2357-4c11-8697-f672bda471ad) --- ### Approval-queue comments: ![immagine](https://projects.blender.org/Francesco-Bellini/extensions-website/pulls/1/attachments/ad58d60a-abf4-41ba-9a60-84d6c7c9f262) --- ### Release notes: ![immagine](/attachments/0e8c7bb2-d677-422a-add9-150d3ce09dbf) ![immagine](https://projects.blender.org/Francesco-Bellini/extensions-website/pulls/1/attachments/09c6d6ed-1797-4691-a1d5-1be97f9d3a42) ### Style match: ![immagine](https://projects.blender.org/Francesco-Bellini/extensions-website/pulls/1/attachments/9fdbaa6f-bc4e-4022-a017-796a34e0afac) --- A mention of markdown preview is made in infrastructure/extensions-website#243. --- I'm available for any kind of changes that might be necessary. From my testing, everything looks good! I wasn't familiar with the Django framework and I'm pretty new to this project, so I tried to look around and search in order to try to blend well in the code.

immagine.png

24 KiB

Francesco Bellini added 2 commits 2024-10-04 02:42:18 +02:00

Feat: API for markdown preview rendering 8691ee5e7b

POST /markdown
calls the same render function as templates

Feat: Markdown preview for markdown-supported fields 15118f16d7

- Add is_markdown_field template filter
- Add tabs Write | Preview on top of the textarea
- Add initMarkdownPreview function to handle tabs content and api fetch client-side

Francesco Bellini force-pushed markdown-preview from 15118f16d7 to 1877cbc936

2024-10-23 16:39:54 +02:00

Compare

This pull request can be merged automatically.

You are not authorized to merge this pull request.

View command line instructions.