Francesco-Bellini/extensions-website
0
0
Fork 0
forked from infrastructure/extensions-website
Code Pull Requests Activity

WIP: Feature: Markdown preview for markdown-supported fields #1

Closed
Francesco Bellini wants to merge 2 commits from markdown-preview into main
pull from: markdown-preview
merge into: Francesco-Bellini:main

When changing the target branch, be careful to rebase the branch in your fork to match. See documentation.
Conversation 0 Commits 2 Files Changed 5 +123 -2
Francesco Bellini commented 2024-10-03 11:04:18 +02:00
Owner
Copy Link

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

Review-process comment:

immagine

Release notes:

immagine
immagine

Style match test:

immagine

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

I'm available for any kind of changes that might be necessary. From my test, everything was fine!
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](/attachments/f79a0546-2357-4c11-8697-f672bda471ad) --- ### Review-process comment: ![immagine](/attachments/ad58d60a-abf4-41ba-9a60-84d6c7c9f262) --- ### Release notes: ![immagine](/attachments/1a9d4490-8559-4b77-9ea5-2ec6caf7adb9) ![immagine](/attachments/09c6d6ed-1797-4691-a1d5-1be97f9d3a42) ### Style match test: ![immagine](/attachments/9fdbaa6f-bc4e-4022-a017-796a34e0afac) --- A mention of markdown preview is made in the issue infrastructure/extensions-website#243. --- I'm available for any kind of changes that might be necessary. From my test, everything was fine! 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
immagine.png
23 KiB
immagine.png
69 KiB
immagine.png
23 KiB
immagine.png
54 KiB
immagine.png
Francesco Bellini added 1 commit 2024-10-03 11:04:19 +02:00
Francesco Bellini changed title from WIP: Feature: Markdown preview for markdown-supported fields. to WIP: Feature: Markdown preview for markdown-supported fields 2024-10-03 11:04:28 +02:00
Francesco Bellini force-pushed markdown-preview from 5bfbc4e3af to ab069f8d5e 2024-10-03 11:10:58 +02:00 Compare
Francesco Bellini reviewed 2024-10-03 11:22:26 +02:00
Francesco Bellini reviewed 2024-10-03 11:23:50 +02:00
Francesco Bellini reviewed 2024-10-03 11:24:20 +02:00
Francesco Bellini reviewed 2024-10-03 11:25:00 +02:00
Francesco Bellini reviewed 2024-10-03 11:26:32 +02:00
Francesco Bellini force-pushed markdown-preview from ab069f8d5e to 4491559e93 2024-10-03 11:31:43 +02:00 Compare
Francesco Bellini force-pushed markdown-preview from 4491559e93 to f24cbdab7a 2024-10-03 11:32:46 +02:00 Compare
Francesco Bellini force-pushed markdown-preview from f24cbdab7a to bd5768d2cf 2024-10-03 16:43:44 +02:00 Compare
Francesco Bellini force-pushed markdown-preview from bd5768d2cf to 07962d9db2 2024-10-03 16:44:31 +02:00 Compare
Francesco Bellini force-pushed markdown-preview from 07962d9db2 to c30a6e22b2 2024-10-03 16:45:10 +02:00 Compare
Francesco Bellini force-pushed markdown-preview from c30a6e22b2 to 59f467c494 2024-10-04 00:04:54 +02:00 Compare
Francesco Bellini force-pushed markdown-preview from 59f467c494 to 4228e9a9f5 2024-10-04 00:15:59 +02:00 Compare
Francesco Bellini force-pushed markdown-preview from 4228e9a9f5 to 0bf7f7d813 2024-10-04 00:46:30 +02:00 Compare
Francesco Bellini force-pushed markdown-preview from 0bf7f7d813 to 8429f36428 2024-10-04 00:49:22 +02:00 Compare
Francesco Bellini force-pushed markdown-preview from 8429f36428 to c200e78798 2024-10-04 01:35:37 +02:00 Compare
Francesco Bellini force-pushed markdown-preview from c200e78798 to cecb3631da 2024-10-04 01:44:52 +02:00 Compare
Francesco Bellini force-pushed markdown-preview from cecb3631da to 71bfd668da 2024-10-04 01:54:53 +02:00 Compare
Francesco Bellini force-pushed markdown-preview from 71bfd668da to 7007189dd1 2024-10-04 02:17:41 +02:00 Compare
Francesco Bellini force-pushed markdown-preview from 7007189dd1 to 969297ac62 2024-10-04 02:19:42 +02:00 Compare
Francesco Bellini force-pushed markdown-preview from 969297ac62 to 4a2eba5514 2024-10-04 02:20:31 +02:00 Compare
Francesco Bellini force-pushed markdown-preview from 4a2eba5514 to 15118f16d7 2024-10-04 02:34:13 +02:00 Compare
Francesco Bellini locked as Off-topic and limited conversation to collaborators 2024-10-04 18:39:54 +02:00

Pull request closed

Please reopen this pull request to perform a merge.
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No Label
Milestone
Clear milestone
No items
No Milestone
Assignees
Clear assignees
No Assignees
1 Participants
Notifications
Due Date
The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: Francesco-Bellini/extensions-website#1
No description provided.
Delete Branch "markdown-preview"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?