feat: Allow markdown in workflow title and description. Fixes #10126 #10553

jmeridth · 2023-02-20T04:54:41Z

Fixes: #10126

new react component for handling workflow row name
new css file to manage row name column
new example file for title and description with markdown
include remark-gfm for GitHub Friendly Markdown (aka urls automatically translate to links)
Add User Guid -> UI Features -> Title and Description docs page

Examples by row:

markdown title, markdown description using remark-gfm to auto turn urls into links
no title or description, defaults to workflow.metadata.name
markdown title, no description
no title, markdown description (title defaults to workflow.metadata.name)
markdown title, markdown description (description includes url that auto turns into anchor
markdown title, markdown description, includes markdown url
markdown title, markdown description, includes markdown url (pr link goes to github.com)

Notes:

CSS could use some work, open to feedback or can file issue for another, more CSS savvy person to "handle"

NOTES

We have 2 choices as I see it regarding how to handle the possible nested links from the markdown generated HTML

Remove the Name column from being under the Link react component
- Add an overlay of CSS to allow users to still click non-markdown links and go to the workflow (the approach we've chosen)
Don't put an overlay and only allow columns 3+ link to the workflow

Downside for both choices - full page refresh, not section refresh like Link component

Why move the name column out from under the `Link` component?

When the Name column was under the Link component, clicking of markdown generated links always still redirected users to the workflow due to the Link react component negating default behavior of the link.

When we pressed cmd/ctrl+link and opened the markdown link in a new tab, however, it worked. This doesn't help us because we have no control of the anchors (links) that are generated from the markdown.

Please do not open a pull request until you have checked ALL of these:

Create the PR as draft .
Run make pre-commit -B to fix codegen and lint problems.
Sign-off your commits (otherwise the DCO check will fail).
Use a conventional commit message (otherwise the commit message check will fail).
"Fixes #" is in both the PR title (for release notes) and this description (to automatically link and close the issue).
Add unit or e2e tests. Say how you tested your changes. If you changed the UI, attach screenshots.
Github checks are green.
Once required tests have passed, mark your PR "Ready for review".

If changes were requested, and you've made them, dismiss the review to get it reviewed again.

jmeridth · 2023-02-21T14:55:54Z

Update: Went with the second one, no extra newline

Do we want a newline between the title and description like this (currently what this PR has):

Or not like this:

Note the meta screenshots? lulz 😄

ui/src/app/workflows/components/workflows-row/workflows-row.scss

jmeridth · 2023-02-23T10:56:42Z

Seems CI is having a rough time the last few runs.

CI / E2E Tests (test-functional, minimal) (pull_request) Cancelled after 25m

Don't see how I can re-run without pushing another commit. If I'm able to re-run I'm not seeing it.

ui/src/app/workflows/components/workflows-row/workflows-row-name.tsx

juliev0 · 2023-02-24T20:14:20Z

Seems CI is having a rough time the last few runs.

CI / E2E Tests (test-functional, minimal) (pull_request) Cancelled after 25m

Don't see how I can re-run without pushing another commit. If I'm able to re-run I'm not seeing it.

Unfortunately, there are intermittent failures. You can push empty commits until it all passes.

jmeridth · 2023-02-24T21:49:06Z

@juliev0 yeah, I've done that before. I think the last few errors were legit re: yarn.lock. Fixed them I think 🤞

jmeridth · 2023-02-24T22:57:05Z

@juliev0 @alexec @terrytangyuan CI finally passed. Would love feedback/approval 😄 pretty please.

jmeridth · 2023-02-28T12:32:36Z

@alexec @terrytangyuan either of you available for a review here? If not, who might be a person to ping? Any UI folks I should query? Thank you for any assistance. Cheers.

caelan-io

Nice work! Thanks for the example. Could you please add doc under "User Guide -> UI features" titled something like "Workflow descriptions" so we have this feature documented in addition to your example?

We unfortunately don't have workflow descriptions documented clearly so it's an under-used feature in my opinion.

I imagine we'll be able to get this merged to master in a March once an approver signs off.

jmeridth · 2023-02-28T17:05:39Z

@caelan-io docs page added. Great suggestion.

docs/title-and-description.md

jmeridth · 2023-03-05T18:16:04Z

@alexec I run make start UI=true every time before I push. The UI works for me locally with my changes when I use the newer react-router-dom. My GitHub actions are failing currently due to rate limiting it seems (HTTP 429) when trying to clone the repo.

alexec · 2023-03-05T18:19:52Z

Build error is error Your lockfile needs to be updated, but yarn was run with --frozen-lockfile. I think you must run yarn install` to fix

jmeridth · 2023-03-05T20:19:01Z

@alexec checks pass and UI running for me locally

jmeridth · 2023-03-06T14:45:28Z

@alexec could the react-router-dom be working for me locally because I'm using node 19? I saw you upgrade the node image in the Dockerfile and went with it. I just noticed we reverted that back to node 16 for LTS.

This might be the culprit with the react-router-dom. But is just a guess.

I need to retest locally with node 16 now. But.....the CI tests pass. Either good or concerning. TBD.

jmeridth · 2023-03-19T15:36:30Z

My PR requires the upgrade to react-router-dom and will not work with node 16. So the decision to downgrade may be a deal breaker for this change. ~~Focusing on LTS versions does need some discussion IMO.~~ LTS makes sense.

I'm also having to add --openssl-legacy-provider to the yarn start NODE_OPTIONS now. That is new.

This was working with node 19 but no longer. Now I have to hunt what else changed. I see the kit inclusion is a decent local development change. LOVE the log files @alexec. Thank you.

jmeridth · 2023-10-18T16:52:58Z

Current issue is the entire workflow row is a link. Have to do some CSS to make the markdown links open their endpoints instead of the workflow detail view in the argo-workflows dashboard.

jmeridth · 2023-12-27T03:02:32Z

Looking into the test failures.

Fixes: argoproj#10126 - [x] new react component for handling workflow row name - [x] new css file to manage row name column - [x] new example file for title and description with markdown - [x] include `remark-gfm` for GitHub Friendly Markdown (aka urls automatically translate to links) - [x] Add User Guid -> UI Features -> Title and Description docs page - [x] make first column of workflow row not be wrapped in row link so markdown links can be clicked - [x] add overlay so users can still click to open workflow - [x] change remark-gfm to 3.0.0 based on remarkjs/react-markdown#771 (comment) Signed-off-by: jmeridth <jmeridth@gmail.com> Co-authored-by: Steven Johnson <52087249+stevenbjohnson@users.noreply.github.com>

terrytangyuan

LGTM

…j#10126 (argoproj#10553) Signed-off-by: jmeridth <jmeridth@gmail.com> Co-authored-by: Steven Johnson <52087249+stevenbjohnson@users.noreply.github.com>

agilgur5

So this ended up getting merged without a UI reviewer on it. There are some issues with the feature as written though, some of which I immediately noticed. There's a typo, a bug in the columns, and some issues with the docs too

For posterity, this was also a topic of discussion in the Jan 2nd Contributor Meeting (which I couldn't attend as it's the biggest holiday for my family)

examples/title-and-descriptin-with-markdown.yaml

docs/title-and-description.md

agilgur5 · 2023-12-30T05:59:38Z

ui/package.json

        "react-monaco-editor": "^0.50.1",
        "react-router-dom": "^4.2.2",
+        "remark-gfm": "^3.0.0",


Do we really need GFM? The features it adds is fairly small, but it is an entire new dep. Most of those features would also not be used, e.g. tables and task lists don't really make sense in this context.

In general, a smaller dep that supports less features would make more sense, as full-featured Markdown in an annotation has some issues and being displayed inside of a list also is a specific context

Given that I spent a solid amount of time improving the UI load time with code-splitting for #12059, we really should be even more careful than we already should be when introducing new, large deps, especially in the UI

On Slack we discussed potentially putting the whole markdown feature behind a feature flag as otherwise the deps load unconditionally for all users, even those who don't use this feature

So we can do an initial code-split and only load the deps if the title and description annotations exist, but it may be difficult to discern if those have markdown specifically without a dep, which is where a feature flag might be good. I still would prefer not to gate it behind a feature flag, but I also don't want the deps loaded for users who don't use the feature.

Code-split this in #12580 based on if the annotations exist, but as written above, can't quite determine if those have markdown without a dep, so there is potentially further action to do here. Maybe there's a clever one-line regex to do it though and then we wouldn't need a dep to detect markdown

ui/src/app/workflows/components/workflows-row/workflows-row.scss

ui/src/app/workflows/components/workflows-row/workflows-row-name.tsx

ui/src/app/workflows/components/workflows-row/workflows-row.tsx

ui/src/app/workflows/components/workflows-row/workflows-row-name.tsx

examples/title-and-descriptin-with-markdown.yaml

agilgur5 · 2024-01-22T06:32:41Z

Also we did discuss the XSS concern offline, JM chose react-markdown specifically for its safety, and I confirmed that myself. I was surprised that it wasn't mentioned in the PR or code review beforehand though, since user-inputted markdown could be a huge injection vector

agilgur5

left some notes on the hacks

ui/src/app/workflows/components/workflows-row/workflows-row.tsx

agilgur5 · 2024-01-22T07:44:11Z

ui/src/app/workflows/components/workflows-row/workflows-row.tsx

@@ -41,16 +42,16 @@ export function WorkflowsRow(props: WorkflowsRowProps) {
                    />
                    <PhaseIcon value={wf.status.phase} />
                </div>
+                <div className='columns small-2'>
+                    <a className='overlay' href={workflowLink}></a>


this is indeed quite hacky as you mentioned in the PR description. I also can't seem to expand the row right now, clicking the "Show" button takes me to the Workflow Details page.

instead of using an a tag, you can use a different element and capture the event and then use navigation.goto to change the route (which is what the Link component does under-the-hood). clicks elsewhere should capture the event first and prevent it from bubbling up to this level.

but tbh, I don't like that the whole thing is a link in the first place, that's very confusing UX-wise as there are different behaviors based on where/when you click. and there's a bunch of text that one may want to copy+paste or highlight, which is basically impossible right now.
so I actually think we should change up the behavior anyway, but I'm not yet quite sure where to put the link to the details page then. maybe we just make the name link to to the Workflow Details and remove the link from everywhere else.

So I removed the whole row being a link in #12580 and made the name only a link.
But then the nested linking issue re-appeared, so I used JS as I mentioned above to prevent bubble up, which is a lot less hacky and less problematic then the overlay CSS (although it still has some semantic issues, as I mention in #12580, but they're technically an edge of an edge case)

jmeridth marked this pull request as ready for review February 20, 2023 05:38

jmeridth requested review from alexec and terrytangyuan February 20, 2023 05:39

jmeridth self-assigned this Feb 20, 2023

jmeridth added the area/ui label Feb 20, 2023

jmeridth force-pushed the jm/allow-for-markdown-in-workflow-title-and-description branch from 753c778 to 5cedf49 Compare February 21, 2023 01:19

jmeridth commented Feb 21, 2023

View reviewed changes

ui/src/app/workflows/components/workflows-row/workflows-row.scss Show resolved Hide resolved

jmeridth added type/dependencies PRs and issues specific to updating dependencies type/feature Feature request javascript Pull requests that update Javascript dependencies labels Feb 23, 2023

jmeridth requested a review from caelan-io February 23, 2023 17:32

juliev0 reviewed Feb 23, 2023

View reviewed changes

ui/src/app/workflows/components/workflows-row/workflows-row-name.tsx Outdated Show resolved Hide resolved

jmeridth requested a review from juliev0 February 24, 2023 01:21

jmeridth force-pushed the jm/allow-for-markdown-in-workflow-title-and-description branch from fc999fb to 9e5f065 Compare February 24, 2023 03:00

juliev0 approved these changes Feb 26, 2023

View reviewed changes

jmeridth force-pushed the jm/allow-for-markdown-in-workflow-title-and-description branch 2 times, most recently from 498ce6f to adafc2d Compare February 26, 2023 20:01

caelan-io approved these changes Feb 28, 2023

View reviewed changes

jmeridth force-pushed the jm/allow-for-markdown-in-workflow-title-and-description branch 2 times, most recently from b95bc24 to b39161e Compare February 28, 2023 17:04

caelan-io reviewed Mar 1, 2023

View reviewed changes

docs/title-and-description.md Outdated Show resolved Hide resolved

jmeridth force-pushed the jm/allow-for-markdown-in-workflow-title-and-description branch 2 times, most recently from 3636854 to 2e85240 Compare March 1, 2023 16:34

jmeridth force-pushed the jm/allow-for-markdown-in-workflow-title-and-description branch 2 times, most recently from 81d5192 to e0075a8 Compare March 5, 2023 19:03

jmeridth force-pushed the jm/allow-for-markdown-in-workflow-title-and-description branch from 6c06fcf to 02af38b Compare March 19, 2023 15:37

jmeridth force-pushed the jm/allow-for-markdown-in-workflow-title-and-description branch from 02af38b to 8162a67 Compare September 20, 2023 14:53

jmeridth force-pushed the jm/allow-for-markdown-in-workflow-title-and-description branch 2 times, most recently from f423a28 to 15f7251 Compare December 27, 2023 02:49

jmeridth force-pushed the jm/allow-for-markdown-in-workflow-title-and-description branch 2 times, most recently from 17e3e70 to a9efa36 Compare December 29, 2023 19:57

jmeridth force-pushed the jm/allow-for-markdown-in-workflow-title-and-description branch from a9efa36 to 416139f Compare December 29, 2023 20:15

jmeridth marked this pull request as ready for review December 29, 2023 20:21

terrytangyuan approved these changes Dec 30, 2023

View reviewed changes

terrytangyuan merged commit 0a8ca81 into argoproj:main Dec 30, 2023
15 checks passed

jmeridth deleted the jm/allow-for-markdown-in-workflow-title-and-description branch January 2, 2024 18:01

agilgur5 reviewed Jan 22, 2024

View reviewed changes

This was referenced Jan 28, 2024

fix(ui): code-split markdown title + desc, fix row linking, etc #12580

Merged

docs(ui): full copy-edit of title & description page #12582

Merged

REQUEST: Promotion to Approver for @agilgur5 argoproj/argoproj#277

Closed

panicboat mentioned this pull request Feb 15, 2024

UI: Support markdown in CronWorkflow/WorkflowTemplate title/description #12644

Open

agilgur5 added this to the v3.6.0 milestone Apr 19, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Allow markdown in workflow title and description. Fixes #10126 #10553

feat: Allow markdown in workflow title and description. Fixes #10126 #10553

jmeridth commented Feb 20, 2023 •

edited

jmeridth commented Feb 21, 2023 •

edited

jmeridth commented Feb 23, 2023

juliev0 commented Feb 24, 2023

jmeridth commented Feb 24, 2023

jmeridth commented Feb 24, 2023

jmeridth commented Feb 28, 2023

caelan-io left a comment

jmeridth commented Feb 28, 2023

jmeridth commented Mar 5, 2023

alexec commented Mar 5, 2023

jmeridth commented Mar 5, 2023

jmeridth commented Mar 6, 2023

jmeridth commented Mar 19, 2023 •

edited

jmeridth commented Oct 18, 2023

jmeridth commented Dec 27, 2023

terrytangyuan left a comment

agilgur5 left a comment •

edited

agilgur5 Dec 30, 2023

agilgur5 Jan 22, 2024

agilgur5 Jan 22, 2024

agilgur5 Jan 28, 2024

agilgur5 commented Jan 22, 2024 •

edited

agilgur5 left a comment

agilgur5 Jan 22, 2024 •

edited

agilgur5 Jan 28, 2024 •

edited

feat: Allow markdown in workflow title and description. Fixes #10126 #10553

feat: Allow markdown in workflow title and description. Fixes #10126 #10553

Conversation

jmeridth commented Feb 20, 2023 • edited

NOTES

Why move the name column out from under the Link component?

jmeridth commented Feb 21, 2023 • edited

jmeridth commented Feb 23, 2023

juliev0 commented Feb 24, 2023

jmeridth commented Feb 24, 2023

jmeridth commented Feb 24, 2023

jmeridth commented Feb 28, 2023

caelan-io left a comment

Choose a reason for hiding this comment

jmeridth commented Feb 28, 2023

jmeridth commented Mar 5, 2023

alexec commented Mar 5, 2023

jmeridth commented Mar 5, 2023

jmeridth commented Mar 6, 2023

jmeridth commented Mar 19, 2023 • edited

jmeridth commented Oct 18, 2023

jmeridth commented Dec 27, 2023

terrytangyuan left a comment

Choose a reason for hiding this comment

agilgur5 left a comment • edited

Choose a reason for hiding this comment

agilgur5 Dec 30, 2023

Choose a reason for hiding this comment

agilgur5 Jan 22, 2024

Choose a reason for hiding this comment

agilgur5 Jan 22, 2024

Choose a reason for hiding this comment

agilgur5 Jan 28, 2024

Choose a reason for hiding this comment

agilgur5 commented Jan 22, 2024 • edited

agilgur5 left a comment

Choose a reason for hiding this comment

agilgur5 Jan 22, 2024 • edited

Choose a reason for hiding this comment

agilgur5 Jan 28, 2024 • edited

Choose a reason for hiding this comment

jmeridth commented Feb 20, 2023 •

edited

Why move the name column out from under the `Link` component?

jmeridth commented Feb 21, 2023 •

edited

jmeridth commented Mar 19, 2023 •

edited

agilgur5 left a comment •

edited

agilgur5 commented Jan 22, 2024 •

edited

agilgur5 Jan 22, 2024 •

edited

agilgur5 Jan 28, 2024 •

edited