Mentionables

[merefield (Robert)]

	Summary	Turn a table in a topic into searchable items that members can mention with +, complete with links and onebox previews.
	Repository	Discourse Mentionables
	Installation guide	Install plugins on a self-hosted Discourse site
	Sponsorship	Please consider sponsoring ongoing development to help keep these plugins maintained and working with current Discourse.

Give your community a shared vocabulary for the things it talks about: books,
products, projects, places, support resources, or anything else with a URL.
Members type + and part of a name, choose a suggestion, and get a readable link without having to remember the address.

Features

• Start with URLs alone. Importer retrieves names and generates slugs; add
  your own names and slugs as optional overrides.
• Search as you write. Type + or use the composer toolbar button to search
  your catalogue. Works in both the Markdown and rich text composers.
• Readable inline links. Mentions appear as compact pills using the item’s
  display name, with a stable slug in the post’s Markdown.
• Native oneboxes. Put a mention on its own line to show a onebox using
  Discourse’s existing layouts and supported destinations.
• Desktop previews. Hover or focus an inline pill to open a floating preview
  with an Open original page link. Ordinary clicks open the destination.
• A catalogue your admins can edit in Discourse. Import from a Markdown table
  in a topic’s opening post. No Google account or API credentials are needed.
• A table button for admins. Insert an empty mentionables table from the
  composer toolbar, then fill in your items.

Onebox appearance depends on the destination and Discourse’s normal onebox
support. Unsupported destinations remain links. Floating cards require login;
guests can still follow the destination link. Mentions in code are left alone,
and mentions in lists and quotes stay inline.

Basic Mentionables and the Pro extension

Basic Mentionables is the base plugin. Pro is an optional companion plugin
installed alongside it; Pro includes the base features through that dependency.

Feature	Basic Mentionables	With Pro extension
Import a Markdown table from a topic’s opening post	Yes	Yes
Keep the source topic in a restricted category	Yes	Yes
Admin-only composer button to insert a table skeleton	Yes	Yes, including icon columns
Search with + in Markdown and rich text composers	Yes	Yes
Inline mention pills and standalone native oneboxes	Yes	Yes
Floating previews on desktop hover or keyboard focus	Yes	Yes, in the default hover mode
Import from Google Sheets using a service account	—	Yes
Select between topic tables and Google Sheets	Topic tables only	Yes
Automatic sync every 12 hours	—	Optional, off by default
Import optional icon names and HTML colours	—	Yes, from either source
Open floating previews on click or tap, including touch devices	—	Optional

Pro’s icon and icon_colour columns add a coloured icon before the mention’s
name. For example, use book and #2563eb for a handbook. With
mentionables_pro_click_to_preview enabled, clicking or tapping a pill opens its
preview; the Open original page link in the preview takes you to the target.

The Pro plugin extension is available for my monthly GitHub sponsors. Sponsor me here to gain access to Pro

Quick setup

1. Install the base plugin using the installation guide above. Rebuild Discourse
   after installation.

2. Create a topic for your catalogue. As an admin, use Insert mentionables
   table in the composer toolbar or paste this table into the opening post:

   | name               | url                                 | slug               | image_url |
   | ------------------ | ----------------------------------- | ------------------ | --------- |
   | Getting started    | https://example.com/getting-started | getting-started    |           |
   | Community handbook | https://example.com/handbook        | community-handbook |           |
   | Events calendar    | https://example.com/events          | events-calendar    |           |
   

3. Replace the example URLs with your own, save the post, and set
   mentionables_topic_id to that topic’s numeric ID. Keep mentionables_enabled
   enabled. Pro installations should select topic_table in mentionables_source
   for this setup.

4. Open Admin → Plugins → Mentionables, click Start import, then
   Refresh to inspect the report. The background job worker must be running.

5. Reload your browser, open a composer, and type + to try your items.

Use lowercase column names. Only url is required, beginning with http://
or https://. URL-only rows retrieve a name from the destination and generate
a slug. You can supply name, slug, or both to override those defaults, mixing
these options within one table. If no title is available, the URL becomes the
display name. Existing URLs retain their slugs when the source omits them.
image_url and description are optional.

The importer reads the first unquoted table with a url column in the opening
post. Replies, quoted tables, and fenced code samples are ignored. Source topics
must be regular, undeleted topics, rather than personal messages.

Source privacy and updating your catalogue

You can keep the source topic in Staff or another restricted category so only
trusted people can maintain it. The imported names, URLs, and images are
available to users of mentionables. Restricting the topic does not make the
imported catalogue private. Keep confidential information out of the table.

Each import synchronizes by URL: matching URLs update, new URLs create records,
and URLs removed from the source delete records. The complete source must be
valid; duplicate URLs or slugs, invalid rows, fetch failures, and empty datasets
leave the catalogue unchanged. Use Delete all for an intentional clear.
Source topics and spreadsheets are never modified. Pro’s optional
mentionables_pro_sync_enabled setting runs the same import every 12 hours.
Reload the browser after importing. Existing cooked posts are not automatically
rebaked, and explicitly changing a slug can break earlier +slug references.

Settings and further information

Setting	Purpose
mentionables_enabled	Enable or disable Mentionables.
mentionables_topic_id	Topic containing the source table in its opening post.
mentionables_autocomplete_limit	Maximum number of suggestions; defaults to five.
mentionables_onebox_fallback	Also retrieve missing images/descriptions when a name is supplied; off by default.

See the README for the full setup guide, import behaviour, and
troubleshooting. The screenshots use sample data from the plugin’s test fixtures.

[Joshua_Kogan]

Can topics be filtered by mentionables? I was thinking of creating a US state dataset, so each post can be related to a state.

[angus (Angus McLeod)]

Not currently. How are you thinking the filter would work in an abstract sense? You can estabilsh any external dataset as a mentionables set. Perhaps you can use an additional column in the data that informs how posts with custom mentionable data would be ordered. Then you’d also need to deal with situations where mutiple mentions were made in the same post. If you scoped out the feature in some detail in an abstract sense we could get a sense of how much it would take to implement it.

[merefield (Robert)]

Originally name was optional and could be derived from og tags - this was lost during a refactor.

I’ve pushed a fix: make name optional again · paviliondev/discourse-mentionables@a7007b2 (github.com)

[merefield (Robert)]

OK I’ve completed a couple of PR’s for this which get things back up and running:

https://github.com/paviliondev/discourse-mentionables/pull/8

Moves the API to Google’s official API, dropping an intermediary gem (and a few others) and adding CI so things should be a bit more reliable going forward.

Please note the breaking changes to settings:

• mentionables_google_spreadsheet_url: “URL of the Google spreadsheet”

becomes:

• mentionables_google_spreadsheet_id: “ID of the Google spreadsheet”

• mentionables_google_worksheet_gids: “Restrict Google spreadsheet import to worksheet GIDs. If empty, all worksheets will be imported.”

becomes:

• mentionables_google_worksheet_names: “Names of in-scope source worksheets (tabs)”

And there is a new setting:

• mentionables_google_worksheet_max_row: “Maximum number of rows scanned”

This fixes the front end (whilst adding tests)

https://github.com/paviliondev/discourse-mentionables/pull/9

[frold]

@angus

Read the documentation

Seems like a dead end…

[RGJ (Richard - Communiteq)]

Thank you for reporting that, I have updated the link.

[frold]

Why is this so technically? Im not even able to set it up and work.

If there were a upload button for the spreadsheet it would have been available for an avg user user like me.

Or a online form editor. This is, sadly, way too advance.

[RGJ (Richard - Communiteq)]

I partly agree with you. This plugin was indeed built for a pretty technical audience. But only the setup is quite hard, after that, the opposite.

In fact, it tries to use a familiar editor by leveraging the power of Google Sheets.

Once it has been setup, any non-technical person can use the plugin in a much easier way than having to upload a file.

[merefield (Robert)]

It’s not suitable for @frold’s use case I suspect which is to present a financial graph rendered by a third party site. Mentionables is not intended for such a use case.

[frold]

if someone would guide via the chat they are welcome to contact me.

I dont think its safe to share the codes via the public forum…

[merefield (Robert)]

@frold there’s no code here for sharing third party graphs. This plugin is not going to help you. It’s purely designed to permit sites to allow users to search and recall from a list of products as grey bubbles that are links to each products page.

[frold]

@merefield

there’s no code here for sharing third party graphs

Okay - I thought it would insert a link into the post.

This url could be to an image, I thought

[merefield (Robert)]

@frold

Okay - I thought it would insert a link into the post.

it does.

@frold

This url could be to an image, I thought

No, it’s just a boring description in a grey bubble

A single additional screenshot would be helpful here I guess

This is just perfect for sets of Affiliate links.

Updated the OP.

[denvergeeks]

Before I go through the setup and config – would an appropriate use-case for mentionables be in writing of Topics which are drafts of legal documents which need to be able to include references to laws and cases, where the connected “mentionables” spreadsheet contains a collection of relevant legal references and case law?

[merefield (Robert)]

That’s sounds like a strong possibility. If you have nice pictures of dusty old books that would help

[merefield (Robert)]

One day I’ve been meaning to add alternative snippets for the same item accessed by pressing + additional times.

[denvergeeks]

OK here are my settings (I’m using the Test Data Google Sheet provided in the setup instructions), and the error I am getting… (apparently the plugin is broken, and the developer requires a fee? Which is fine, of course, just FYI!)

Any help would be much appreciated!

[merefield (Robert)]

It’s still working, make sure your private key starts: -----BEGIN PRIVATE KEY---- and ends -----END PRIVATE KEY-----

[RGJ (Richard - Communiteq)]

@denvergeeks

apparently the plugin is broken, and the developer requires a fee

No, it’s working - and free. Why did you think that?