Auto Bookmarks plugin

[acaporrini (Alessandro Caporrini)]

discourse-auto-bookmarks

discourse-auto-bookmarks is a Discourse plugin for adding automatic HTML bookmarks to topics and easily get a sharable link which points at specific parts of the text.

Installation

Follow Install a Plugin
how-to from the official Discourse Meta, using git clone https://github.com/acaporrini/discourse-auto-bookmarks.git
as the plugin command.

Usage

Hover over any h1,h2,h3,h4,h5,h6 header in your topics, a small bookmark icon will appear:

Right click the bookmark icon and select “Copy link address”:

Now you can share this bookmark link, it will open the topic exactly at the point where the bookmark is.

Testing

To run tests in your local environment visit http://localhost:3000/qunit?qunit_skip_core=1&qunit_single_plugin=discourse-auto-bookmarks

Repository

https://github.com/acaporrini/discourse-auto-bookmarks

[pfaffman (Jay Pfaffman)]

Could this be a theme component?

It looks like this adds #target links to H[1-6], right? I’ve seen discussion about this before and the solution was to insert HTML in the Markdown to create the targets. It seems like it’d be easy enough to roll that into core.

[TheBestPessimist]

This is brilliant! Why isn’t this functionality in core already?

[Falco]

@pfaffman

It seems like it’d be easy enough to roll that into core.

@TheBestPessimist

Why isn’t this functionality in core already?

When @eviltrout added the anchor functionality in core he did postpone the automagic anchor creation because it’s not that simple, since you need to pick up a pattern, parse the entire post to deduplicate anchors, etc

@eviltrout

Going forward, we might want to consider auto generating ids for heading tags. Github’s markdown engine does this. For example, <h3>test</h3> automatically becomes <h3 id='test'>test</h3> so you don’t have to worry about adding the id yourself.

There are downsides to this approach if we do it - in particular it’s difficult to handle headings with the same name. There is more detail here if you are interested in reading more.

[pfaffman (Jay Pfaffman)]

That explains it. I mostly think that anyone who cares about the ability to link to headings would also bother to make them unique. It doesn’t seem that bad if a link goes the wrong place if someone is careless. That’s what HTML does, after all. (But maybe there’s something else I’m missing.)

[fguillen]

Very nice and very useful functionality I was actually missing it

[tobiaseigen]

Nice work, @acaporrini! Thanks for contributing this nifty plugin. Is there any way you could envision adding a shortcode e.g. [toc] to generate a table of contents of headings and sub-headings within a post? This would make a long term dream a reality for me.

@acaporrini

a small bookmark icon will appear:

I’m not sure this blue bookmark icon is really needed - it would be fine, in my view, for this to be a hidden feature that power users can use to deep link to sections within posts.

@acaporrini

Installation

Follow Install a Plugin
how-to from the official Discourse Meta, using git clone https://github.com/acaporrini/auto-bookmarks.git
as the plugin command.

Typo? Looks like this URL should be

https://github.com/acaporrini/discourse-auto-bookmarks.git

@pfaffman

That explains it. I mostly think that anyone who cares about the ability to link to headings would also bother to make them unique. It doesn’t seem that bad if a link goes the wrong place if someone is careless. That’s what HTML does, after all. (But maybe there’s something else I’m missing.)

I agree strongly with this. I would love to see this feature in core even without deduping anchors within posts. The benefits far outweigh the risks.

[sam (Sam Saffron)]

The issues I think we would have with adding this into core is

1. We definitely do not want all H2 / H3 etc to become hyperlinks
2. Relying on hover here means touch has no solution
3. Hover may be a bit noisy as you scroll around, especially since it shuffles an element on to the page

That said I am totally for some new syntax in core, if we can work it out. Something like this maybe, I don’t know:

### I am a heading

[This is a bookmark to heading](#i-am-a-heading)

[tobiaseigen]

I’m noticing an odd bug on my site - see screenshot. The alignment is off and all but first line get beginning cut off when a heading is shown that is long and goes over one line.

[tobiaseigen]

The syntax you are suggesting looks great to me!

I don’t think we’d need to rely on hover and agree it is noisy. Maybe headings can simply become links to themselves that can be selected via long press or ctrl/right click? Only issue there would be headings where people create links as in eg below, but not sure this would matter for the vast majority of cases.

# [this is a heading](https://someurl.com)

I still like @mcwumbly’s suggestion from back in the day:

@mcwumbly

I would look at what Google Docs does as a model. They include H1-H6 in the ToC.

The workflow would be something like:

1. Write a post with headers
2. Click a button in the “gear icon dropdown” to generate a ToC
3. ToC is an outline with links to the headings, indented by heading level
4. ToC is just markdown inserted into the composer that you can edit/delete
5. Clicking the “generate ToC” buttons would not replace the existing ToC, but instead, just insert a new one.*

• this is different than what Google Docs does, but probably a lot easier and completely acceptable in my opinion.