feat: add citation popup for blog posts (fixes #3322) by SyedIshmumAhnaf · Pull Request #3332 · matrix-org/matrix.org

SyedIshmumAhnaf · 2026-04-03T21:53:36Z

Description

Adds a citation popup modal for blog posts and adds option to copy citation.

Related issues

Closes #3322.

Role

Individual

Timeline

No specified deadline

Signoff

Signed-off-by: Ishmum

Screenshots

github-actions

Thanks for contributing to the matrix.org website. I have automatically marked your pull request as a draft. Please restore the PR template to your PR description and follow our contributing guidelines, then undraft to let the team know the PR is ready for review.

github-actions

Thanks for contributing to the matrix.org website. I have automatically marked your pull request as a draft. Please restore the PR template to your PR description and follow our contributing guidelines, then undraft to let the team know the PR is ready for review.

github-actions

Thank you for applying the PR template. The PR is now ready for review by a human.

awtj8o81ryywg793

Alongside the included comments, I wonder whether it would be better to use a macro or shortcode instead, in case we want to include the same component elsewhere in the future.

SyedIshmumAhnaf · 2026-04-05T18:07:05Z

Hello. Thank you for the detailed feedback, this is really helpful. I understand the architectural concerns raised here, especially around keeping styling within /sass and avoiding runtime JavaScript where build-time generation is more appropriate.

Based on your suggestions, I am planning to refactor this PR as follows:

I will move all styles into the Sass pipeline to align with existing conventions
Then I intend to replace the JavaScript-based citation generation with a Zola macro so citations are generated at build time
Once that's done, I will rework the toggle behavior to follow the same pattern used in the navigation (as seen in header.html and _header.scss), so that I can avoid dependency on JavaScript for core functionality
Also, I want to keep JavaScript only for progressive enhancement, for example, copy-to-clipboard, accessibility improvements.
Lastly i will restructure the citation logic so that we can allow future support for multiple formats, since APA is implemented initially.

I’ll push an updated version shortly following this approach. Also, I agree that using a macro (or shortcode) makes this more reusable across the site. I’ll incorporate that into the refactor. Let me know if there’s anything else I should consider while making these changes.

awtj8o81ryywg793 · 2026-04-05T22:51:25Z

Quoted from a previous comment:

Then I intend to replace the JavaScript-based citation generation with a Zola macro so citations are generated at build time

Just to be clear, my suggestion was to make the component itself, not just the citation‑generation part, a macro and include it in templates/post.html.

Lastly i will restructure the citation logic so that we can allow future support for multiple formats, since APA is implemented initially.

In addition to supporting APA, it would be nice to add support for MLA, Chicago, Harvard and possibly BibTeX within this PR.

If you have any questions, feel free to reach out either here on GitHub or in #matrix.org-website:matrix.org.

SyedIshmumAhnaf · 2026-04-06T12:47:26Z

Thank you for the clarification, this helps a lot. I understand the intention more clearly now. I’ll make the entire citation component reusable via a macro or shortcode and include it in templates/post.html. I’ll refactor so that the macro outputs the full component.

Also, regarding the different citation formats, I’ll update the implementation to also include MLA, Chicago, Harvard and BibTeX in this PR.

Lastly, I’ll ensure that my component follows the existing pattern the project uses in header.html and _header.scss for toggling behavior so that it does not rely on Javascript for core functionality.

I’ll push an updated version. Thanks again for the guidance.

SyedIshmumAhnaf

Hello again, as per our last discussion, I have refactored the codes and pushed an update. The primary changes made are as follows:

Using a cleaner macro structure with consistent fallback handling
Improved accessibility in the modal
Refactored SCSS for better readability and maintainablity
Added a tab switching logic for different citation formats, APA, BibTex, Harvard, etc.

SyedIshmumAhnaf

As per our last discussion, I've made a few changes to the codebase to remove js based techniques and replace with a css only approach. I have also added option for other citation formats.

awtj8o81ryywg793

I haven't addressed how each citation style conforms to its respective style guide in this review; I'll cover that in a separate review later.

Alongside the requested changes, I'd like the button's appearance updated to match the other buttons used on the website.

awtj8o81ryywg793 · 2026-04-16T12:13:02Z

I edited your original comment to include the “closes” keyword so that merging this PR will automatically close the issue.

SyedIshmumAhnaf · 2026-04-16T20:54:51Z

Thanks for the detailed review. I’ve addressed the requested changes. To summarize, here is what has changed:

Simplified author checks
Added SPDX header
Removed inline comments
Removed citation respective comments

Would you mind taking another look when you have a moment?

awtj8o81ryywg793 · 2026-04-17T22:05:32Z

Thank you for d35e0b6. While I look into the formatting of each citation type, could you add support for copy-to-clipboard functionality as a progressive enhancement?

SyedIshmumAhnaf · 2026-04-18T16:31:00Z

Sure, I'll look into it.

SyedIshmumAhnaf · 2026-04-25T11:25:41Z

Hello @awtj8o81ryywg793, As previously discussed, I’ve added copy-to-clipboard support as a progressive enhancement.

The citation text is still generated at build time, and the modal/tabs continue to work without JavaScript. The copy controls are hidden by default and are only enabled when the Clipboard API is available, so the no-JS fallback remains manual selection/copying from the visible citation text.

I hope this gets merged soon.

SyedIshmumAhnaf

Hi @awtj8o81ryywg793, thanks for the detailed feedback. I’ve pushed an update addressing all the points raised.

Changes made:

Moved .cite-panel into the existing {% for fmt in formats %} loop to remove duplicated markup
Reworked the copy-to-clipboard UI to use a single shared copy button, positioned below the citation textbox
Moved the “Copied” status next to the button for clearer feedback
Updated the copy button styling to use the existing .call-to-action pattern for consistency with the rest of the site
Updated the JS to copy based on the currently selected format (via the active radio input)

The progressive enhancement approach is preserved:

No-JS users can still access the modal and switch formats as before
Copy controls are only enabled when the Clipboard API is available

I’ve tested this locally across all formats and everything appears to be working as expected, but happy to adjust further if needed.

Here is a screenshot of the UI for reference:

awtj8o81ryywg793

In regard to the buttons, I had something like this in mind:

Aside from the buttons, see the other feedback as part of this review.

SyedIshmumAhnaf

Hi, thanks for the follow-up review and the UI example.

I’ve pushed another update addressing the latest feedback:

Updated the copy interaction so the button label remains “Copy”, with status shown only via the adjacent status text
Switched the copy button to call-to-action (removed secondary) and adjusted sizing to better match the modal
Applied the suggested compact pill styling to .cite-btn and .cite-format-tab for consistency with the provided example
Ensured all citation controls follow a consistent visual style within the modal

Everything has been tested locally (all formats + no-JS fallback) and zola build passes with no new issues.

Let me know if anything still feels off or needs further refinement.

awtj8o81ryywg793 · 2026-05-05T08:47:38Z

Quoted from a previous comment:

Hi, thanks for the follow-up review and the UI example.

I’ve pushed another update addressing the latest feedback:
* Updated the copy interaction so the button label remains “Copy”, with status shown only via the adjacent status text

* Switched the copy button to `call-to-action` (removed `secondary`) and adjusted sizing to better match the modal

* Applied the suggested compact pill styling to `.cite-btn` and `.cite-format-tab` for consistency with the provided example

* Ensured all citation controls follow a consistent visual style within the modal
Everything has been tested locally (all formats + no-JS fallback) and zola build passes with no new issues.

Let me know if anything still feels off or needs further refinement.

Thanks! I'll review your changes and get back to you as soon as I can.

awtj8o81ryywg793

After stepping back from the pull request for a bit, I think that, instead of showing a single format selectable via buttons, we should mirror the design in the original issue (i.e. show all formats at once, organised in a vertical list).

I also think it might be worth moving away from using <label> elements for toggle functionality, since the popover attribute has good browser support. Also, while linking multiple <label> elements to a single <input> works, it isn't valid. See: https://developer.mozilla.org/docs/Web/HTML/Reference/Global_attributes/popover.

I apologise for the churn in this pull request. After these changes, and once we’ve revisited the formatting of the citations themselves, this should be good to go.

awtj8o81ryywg793 · 2026-05-24T23:20:44Z

+
+        <div class="cite-formats">
+
+            {% set formats = ["apa", "mla", "chicago", "harvard", "bibtex"] %}


Let's move this to below the definition of cb_id on line 6.

awtj8o81ryywg793 · 2026-05-24T23:28:56Z

+</div>
+
+{% endmacro render %}
+


Suggested change

awtj8o81ryywg793 · 2026-05-24T23:29:05Z

+{{ authors }}. ({{ year }}). {{ page.title }}. Matrix.org. {{ page.permalink }}
+{%- endmacro cite_apa %}
+
+


Suggested change

awtj8o81ryywg793 · 2026-05-24T23:29:11Z

+{{ authors }}. "{{ page.title }}." Matrix.org, {{ date_fmt }}, {{ page.permalink }}.
+{%- endmacro cite_mla %}
+
+


Suggested change

awtj8o81ryywg793 · 2026-05-24T23:29:17Z

+{{ authors }}. "{{ page.title }}." Matrix.org. {{ date_fmt }}. {{ page.permalink }}.
+{%- endmacro cite_chicago %}
+
+


Suggested change

awtj8o81ryywg793 · 2026-05-24T23:29:22Z

+{{ authors }} ({{ year }}) '{{ page.title }}', Matrix.org, viewed {{ date_fmt }}, <{{ page.permalink }}>.
+{%- endmacro cite_harvard %}
+
+


Suggested change

…ation macro structure in Zola templates keeping a standardized fallback logic for authors and dates. Refactored SCSS for better maintainability. Also, added and fixed tab switching logic for different formats. Lastly, no major changes were made regarding output formatting and instead matched zola formatting. Signed-off-by: Syed Ishmum Ahnaf syedishmum15@gmail.com

Co-authored-by: Jack S. <181536874+awtj8o81ryywg793@users.noreply.github.com> Signed-off-by: Syed Ishmum Ahnaf <syedishmum15@gmail.com>

…tion and updated section with page.taxonomies.author only. Signed-off-by: Syed Ishmum Ahnaf syedishmum15@gmail.com

…um15@gmail.com

…yed Ishmum Ahnaf syedishmum15@gmail.com

…s to render .cite-panel via loops. Now, using one single copy button, which matches styling with .call-to-action, below citation text. Preserved no-JS fallback. Signed-off-by: Syed Ishmum Ahnaf syedishmum15@gmail.com

…copy status in the adjacent status element only and preserved Copy button label after clipboard action. Also, applied compact pill styling and using call-to-action styling for the copy button. Signed-off-by: Syed Ishmum Ahnaf <syedishmum15@gmail.com>

Signed-off-by: Syed Ishmum Ahnaf <syedishmum15@gmail.com>

SyedIshmumAhnaf · 2026-05-27T10:49:11Z

Hi @awtj8o81ryywg793, no worries about the churn. I’ve pushed an update implementing the latest requested refactor:

Replaced the checkbox/label-based toggle with the native popover / popovertarget approach
Removed the radio/tab-based single-format view
Updated the citation popup to show all formats at once in a vertical list, matching the direction from the original issue
Moved formats directly below the cb_id definition
Updated copy-to-clipboard behavior so each visible citation format has its own local copy button/status
Removed the old tab/radio-specific Sass and JS logic

I tested this locally and checked that everything works as expected. I’ve left the citation-formatting macro outputs intact for now, since you mentioned the formatting itself will be revisited separately after this UI/structure change.

SyedIshmumAhnaf requested a review from a team as a code owner April 3, 2026 21:53

github-actions Bot marked this pull request as draft April 3, 2026 21:53

github-actions Bot added the missing-template This PR had the template removed from its description. Please add back and follow the instructions. label Apr 3, 2026

github-actions Bot requested changes Apr 3, 2026

View reviewed changes

SyedIshmumAhnaf closed this Apr 3, 2026

SyedIshmumAhnaf deleted the fix_cite branch April 3, 2026 22:11

SyedIshmumAhnaf restored the fix_cite branch April 3, 2026 22:15

SyedIshmumAhnaf reopened this Apr 3, 2026

github-actions Bot requested changes Apr 3, 2026

View reviewed changes

SyedIshmumAhnaf marked this pull request as ready for review April 3, 2026 22:18

github-actions Bot removed the missing-template This PR had the template removed from its description. Please add back and follow the instructions. label Apr 3, 2026

github-actions Bot approved these changes Apr 3, 2026

View reviewed changes

awtj8o81ryywg793 requested changes Apr 4, 2026

View reviewed changes

Comment thread templates/post.html Outdated

Comment thread templates/post.html Outdated

HarHarLinks added the enhancement This would be an improvement to the website. label Apr 5, 2026

SyedIshmumAhnaf commented Apr 9, 2026

View reviewed changes

SyedIshmumAhnaf force-pushed the fix_cite branch from 9311595 to 166f022 Compare April 9, 2026 22:03

SyedIshmumAhnaf commented Apr 9, 2026

View reviewed changes

awtj8o81ryywg793 requested changes Apr 16, 2026

View reviewed changes

awtj8o81ryywg793 requested changes Apr 17, 2026

View reviewed changes

Comment thread sass/_citation.scss Outdated

awtj8o81ryywg793 requested changes Apr 25, 2026

View reviewed changes

Comment thread templates/macros/citation.html Outdated

SyedIshmumAhnaf commented Apr 26, 2026

View reviewed changes

awtj8o81ryywg793 requested changes Apr 28, 2026

View reviewed changes

Comment thread static/js/citation.js Outdated

Comment thread static/js/citation.js Outdated

Comment thread templates/macros/citation.html Outdated

Comment thread sass/_citation.scss

Comment thread sass/_citation.scss

Comment thread sass/_citation.scss Outdated

SyedIshmumAhnaf commented Apr 28, 2026

View reviewed changes

awtj8o81ryywg793 requested changes May 25, 2026

View reviewed changes

SyedIshmumAhnaf and others added 9 commits May 27, 2026 15:58

feat: add citation popup for blog posts (fixes matrix-org#3322)

d787d86

Apply suggestion from @awtj8o81ryywg793

7569110

Co-authored-by: Jack S. <181536874+awtj8o81ryywg793@users.noreply.github.com> Signed-off-by: Syed Ishmum Ahnaf <syedishmum15@gmail.com>

cleaned up #added, removed comments for citations, added SPDX informa…

0445d05

…tion and updated section with page.taxonomies.author only. Signed-off-by: Syed Ishmum Ahnaf syedishmum15@gmail.com

Updated the copyright text. Signed-off-by: Syed Ishmum Ahnaf syedishm…

596f038

…um15@gmail.com

feat(citation): added copy-to-clipboard enhancement. Signed-off-by: S…

a5c53b0

…yed Ishmum Ahnaf syedishmum15@gmail.com

refactor(citation): use popover with vertical citation list

1ce793d

Signed-off-by: Syed Ishmum Ahnaf <syedishmum15@gmail.com>

SyedIshmumAhnaf force-pushed the fix_cite branch from c310229 to 1ce793d Compare May 27, 2026 10:40


		<div class="cite-formats">

		{% set formats = ["apa", "mla", "chicago", "harvard", "bibtex"] %}

		{{ authors }}. ({{ year }}). {{ page.title }}. Matrix.org. {{ page.permalink }}
		{%- endmacro cite_apa %}

		{{ authors }}. "{{ page.title }}." Matrix.org, {{ date_fmt }}, {{ page.permalink }}.
		{%- endmacro cite_mla %}

		{{ authors }}. "{{ page.title }}." Matrix.org. {{ date_fmt }}. {{ page.permalink }}.
		{%- endmacro cite_chicago %}

		{{ authors }} ({{ year }}) '{{ page.title }}', Matrix.org, viewed {{ date_fmt }}, <{{ page.permalink }}>.
		{%- endmacro cite_harvard %}

Uh oh!

Conversation

SyedIshmumAhnaf commented Apr 3, 2026 • edited by awtj8o81ryywg793 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Related issues

Role

Timeline

Signoff

Screenshots

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

awtj8o81ryywg793 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

SyedIshmumAhnaf commented Apr 5, 2026

Uh oh!

awtj8o81ryywg793 commented Apr 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

SyedIshmumAhnaf commented Apr 6, 2026

Uh oh!

SyedIshmumAhnaf left a comment

Choose a reason for hiding this comment

Uh oh!

SyedIshmumAhnaf left a comment

Choose a reason for hiding this comment

Uh oh!

awtj8o81ryywg793 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

awtj8o81ryywg793 commented Apr 16, 2026

Uh oh!

SyedIshmumAhnaf commented Apr 16, 2026

Uh oh!

Uh oh!

awtj8o81ryywg793 commented Apr 17, 2026

Uh oh!

SyedIshmumAhnaf commented Apr 18, 2026

Uh oh!

SyedIshmumAhnaf commented Apr 25, 2026

Uh oh!

Uh oh!

SyedIshmumAhnaf left a comment

Choose a reason for hiding this comment

Uh oh!

awtj8o81ryywg793 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

SyedIshmumAhnaf left a comment

Choose a reason for hiding this comment

Uh oh!

SyedIshmumAhnaf commented Apr 3, 2026 •

edited by awtj8o81ryywg793

Loading

awtj8o81ryywg793 left a comment •

edited

Loading

awtj8o81ryywg793 commented Apr 5, 2026 •

edited

Loading

awtj8o81ryywg793 left a comment •

edited

Loading

awtj8o81ryywg793 left a comment •

edited

Loading