Slug based linked headlines in volto-slate

[nileshgulia1]

PLIP (Plone Improvement Proposal)

Responsible Persons

Proposer: Nilesh Gulia @nileshgulia1

Seconder: Tiberiu Ichim @tiberiuichim

Abstract

Add a anchor link target to headings(h1,h2,h3,h4) in volto-slate.

Motivation

We often came across situations where we might want to direct a user to specific section/heading(h1,h2,h3,h4) in a page. We need an ability to create those anchors links within headings written in volto-slate.

Assumptions

For every new widget/block, UniversalLink component should be used for rendering links.

Proposal & Implementation

Proposal is to display a link button when hovering on a specific heading in volto-slate hitting which creates an anchor based on slugiffied heading title and stored as an id attribute on an element. IMO, this is a most useful basic feature missing in a modern day CMS and quite a common solution on many sites.

Example: https://learn.microsoft.com/en-us/power-platform/alm/overview-alm#what-is-alm <h2 id="introduction-to-everything">Introduction to everything</h2>

Deliverables

• [x] link svg on hover headings
• [x] sluggified anchors based on heading title
• [x] github-slugger npm package
• [ ] Existing blocks toc, links?
• [ ] What about the title block?
• [ ] Css and animations on scroll
• [x] UniversalLink component now uses react-router-hash-link
• [ ] Cypress tests

Risks

• Using sluggified anchors can break existing blocks such as TOC and other widgets which are based on block uids.
• What will happen to slug if headings are modified? and/or existing headings?
• Could be a potential breaking change?
• opt-in feature?

Participants

• @tiberiuichim https://github.com/plone/volto/pull/3540
• @nileshgulia1 https://github.com/plone/volto/pull/4287

To be discussed in next @plone/volto-team meeting.

[stevepiercy]

How would you handle hover states on mobile devices without a mouse? Tap and hold?

[tiberiuichim]

@stevepiercy on mobile, the headline links should be visible directly (not hidden), similar to the way github does it.

[nileshgulia1]

For the record, this is how the current implementation looks

mobile:

Desktop:

The title block isn't a part of this feature yet as it doesn't support rich text editing. We might also need to modify https://github.com/plone/volto/blob/linkedHeadlinesRefactor/src/components/manage/Blocks/Title/Edit.jsx#L146

[akshatgarg12]

Planning to propose a solution to this as contributor in GSOC'23.

My views regarding the risks , based on the current implementation in #3540 and #4287,

What will happen to slug if headings are modified? and/or existing headings?

As the slug is based on the content of the LinkedHeadings , the slug will be dynamic and will be generated based on the headings text, so the id will change accordingly ( as implemented here )

Using sluggified anchors can break existing blocks such as TOC and other widgets which are based on block uids.

In #4287 , the TOC component renderListItems has a slug generated by the plaintext of the block which should be able to maintain consistency and not break the TOC

Could be a potential breaking change?

This will be a breaking change for projects which have used component shadowing for components like title, TOC, TextBlockView

opt-in feature

Making it an opt-in feature at component level will again be a breaking change for the above components, and will we use conditional rendering in this case?

Please correct me if I'm wrong in these assumptions cc : @tiberiuichim @nileshgulia1

[rakshith6404]

I would like and am planning to contribute to this project/idea as a contributor and an aspirant of GSoC'23,

Looking forward for the solution needed and making a detailed proposal for the same is what i am planning to get going to this project,I have started to work on this issue and have some deliverables from my side which i have stated in the proposal.

As in the part of Risks @nileshgulia1 haas stated ;

Using sluggified anchors can break existing blocks such as TOC and other widgets which are based on block uids.

I have a solution to this issue and have started writing my proposal regarding the same.

I am looking forward for the mentors cc: @tiberiuichim @nileshgulia1 and the mentor of this Project/idea to guide me through it and also could the CCs Please guide me how to start contributing to this issue.Should i just submit the proposal when the timeline for the submission for the project starts??

[sneridagh]

@plone/volto-team This is how Confluence is implementing it, and I kind of like it:

https://user-images.githubusercontent.com/486927/229339076-5da723da-adfa-44d2-b3b5-5d69cb603e9b.mov

[tiberiuichim]

@sneridagh can you do a test with a multiline headline? I wonder how they treat this case, if the link icon is inline with the end of the text, or at the side.

[sneridagh]

At the end of the text:

https://user-images.githubusercontent.com/486927/229340509-39bfda49-0ddb-4b05-84d7-dbfef4bf54a2.mov

[nileshgulia1]

After adding some animations and css it finally took the shape.

https://user-images.githubusercontent.com/22280901/232764591-3828dab5-9dad-4430-9502-79b513aa634e.mov

[sneridagh]

Closing as completed in #3540

[tisto]

@nileshgulia1 @tiberiuichim @avoinea @sneridagh I am currently writing the roadmap for Plone 6.x and I try to include links to the documentation of a new feature. So far I only found:

https://6.docs.plone.org/volto/configuration/volto-slate/index.html https://6.docs.plone.org/volto/configuration/volto-slate/configuration-settings.html#slate-uselinkedheadings

Is this everything we got/need?

[nileshgulia1]

@tisto That's only what I found. It would be nice to mention it in the user manual as well.

[tisto]

@nileshgulia1 could you imagine working on some user docs for this feature?