Mkdocs-material: Proposal for Hypothesis integration

[jfix]

I'm interested in creating an extension that is quite similar to Disqus. The result will be the same, i.e. the integration of a discussion/annotation tool, except it's not Disqus but Hypothes.is. Here's a link to how this gets integrated manually.

From what I've seen by looking at the code for Disqus it's really quite similar, it comes down to including an embed.js and configuring the behaviour via some options.

My questions are:

1. Would you accept an integration like this as a PR?
2. Are there any other places in the code to modify in order make such an integration work?

Thanks.

Edit: regarding question 2, there is of course the base.html file that would need an update, too.

[squidfunk]

First of, it’s great that you opened an issue for discussing this matter before implementing. It saves us both a lot of time discussing a strategy beforehand.

1. Would you accept an integration like this as a PR?

That depends on whether it solves a problem that a reasonable fraction of users have. Personally I’ve never heared of Hypothesis. What’s the upside to using Disqus? Is Hypothesis actually used by other websites? How big is the need? I would want to make sure that it solves something Disqus can’t. I’m general, integrating another comment system increases maintenance on my side.

1. Are there any other places in the code to modify in order make such an integration work?

The Disqus integration is very simple as I assume Hypothesis should be too. If it’s as easy as Disqus, just one line of HTML in the base template (or where you want to have it) and some custom JavaScript and you should be good to go.

[squidfunk]

I had a second look at their website and saw the demo - so as I understand Hypothesis is more about annotations then a commenting system, correct? This, actually, would be kind of great to have for Material. Is the Chrome extension mandatory or would someone who visits Material without it benefit from it?

[jfix]

You're right it's foremost an annotation system, so not really comparable to Disqus.

The Chrome extension is optional, it's mainly useful for websites that don't provide a Hypothesis sidebar. Websites can provide the Hypothesis sidebar in any case, and people won't need the Chrome extension.

If you like, from my understanding (I have no relationship with Hypothesis), the extension is to enable 'users' to use Hypothesis, while the sidebar is for 'publishers' who want to encourage use of Hypothesis.

[squidfunk]

Could you prototype and deploy a demo or link to a site which implemented it the way you’re planning to do?

[jfix]

Yes, that sounds like a good idea. I'll try to do that in the coming days.

[jfix]

Ok, so here we go, on a relatively vanilla Mkdocs Material site (ignore the content if you can):

1. Sidebar minimized, using the default 'classic' theme
2. Sidebar open on page load, again using 'classic'
3. Sidebar open on page load, with what they call 'clean' theme but this doesn't really work very well, because when you close the sidebar you can't open it again, because there's no button to make it reappear. Something to look into maybe with the Hypothesis folks.

Note that the sidebar doesn't appear immediately on page load which is not necessarily a bad thing.

As you can see, it works quite well for the 'classic' theme, except for the fact that Hypothesis adds some kind of gutter to the right-hand side of the page which seems to have as a consequence some slight overlap of the sidebar with the actual text. That could probably be solved by adapting the CSS.

The options (sidebar open or closed, highlights of text shown initially or not, etc.) are documented. The majority of the config options can be simply added as an anonymous JSON object, like I did for the second and third bullet points above:

<script type="application/json" class="js-hypothesis-config">
 {
      "openSidebar": true,
      "theme": "clean"
 }
</script>

For certain specific needs, some event-related options need a JavaScript function definition instead. I'm not sure whether that is a problem.

On mobile, hiding the sidebar by clicking the corresponding button on the top-left of the sidebar has as an unwelcome side effect that the table of contents of the current page is shown because somehow the tap/click on the close button of the sidebar is also caught by the table of contents.

[squidfunk]

Thanks for creating a prototype!

Note that the sidebar doesn't appear immediately on page load which is not necessarily a bad thing.

It's the same for Disqus, as it's integrated with JavaScript. Not a problem.

As you can see, it works quite well for the 'classic' theme, except for the fact that Hypothesis adds some kind of gutter to the right-hand side of the page which seems to have as a consequence some slight overlap of the sidebar with the actual text. That could probably be solved by adapting the CSS.

On desktop, opening it on load is probably not a good idea from a UX perspective, as it may overlay the table of contents (or content on smaller screens) if there's any on the site.

The options (sidebar open or closed, highlights of text shown initially or not, etc.) are documented. The majority of the config options can be simply added as an anonymous JSON object, like I did for the second and third bullet points above

This could in theory be done with a pretty thin theme integration which could be configurable like this:

extra:
  hypothesis:
    open_sidebar: true
    theme: 'clean'

On mobile, hiding the sidebar by clicking the corresponding button on the top-left of the sidebar has as an unwelcome side effect that the table of contents of the current page is shown because somehow the tap/click on the close button of the sidebar is also caught by the table of contents.

This is actually a big problem, as it cripples the mobile UX. It's sadly I point I would regard as a show stopper for a direct integration into Material. Furthermore, I thought that, as a user browsing the site, you could view the annotations without creating an account, but it seems that an account is mandatory to do anything with Hypothesis, or is it?

[jfix]

Thanks for your comments. I like the configuration YAML example. :-)

Regarding the mobile UX:

1. The problem occurs when using small screens like mobile phones because the width of the sidebar seems to be fixed. It is fine when using a device with a width of 425px (just by experimenting with Chrome's dev tools). [... doing some more testing ...] Devices like iPhone X are also concerned.
2. I would find it acceptable to not expose this (advanced) functionality at all on devices with a width below, via a media query for example.
3. I will see whether there is a possibility to configure the sidebar width. I will also see whether there is interest in the Hypothesis community to help with this issue.

Regarding the necessity of an account with Hypothesis: It is true that you need an account. But I'd hope that's not blocking as the same, I think, is true for Disqus.

Regarding the sidebar open on page load configuration: I agree with you that it hides the table of contents, but this was just to show that it's possible and for me it also showed that there is this slight overlap of the sidebar with the contents to the left. This could be solved via some CSS tweaks, right?

[squidfunk]

1. The problem occurs when using small screens like mobile phones because the width of the sidebar seems to be fixed. It is fine when using a device with a width of 425px (just by experimenting with Chrome's dev tools). [... doing some more testing ...] Devices like iPhone X are also concerned.

I try to provide a good experience for everything above 320px. There are, still, smaller phones out there, for example the iPhone 4 and 5 (think of emerging markets).

1. I would find it acceptable to not expose this (advanced) functionality at all on devices with a width below, via a media query for example.

While one could argument that you could tilt the device and use it in landscape mode, I don't really like changing functionality based on screen size (or device orientation). Nevertheless, it must be possible to register and deregister Hypothesis when you want to trigger it based on Media Queries (don't onow if that's possible), as you cannot simply hide it with CSS, because there's an overlay when you highlight text which would be shown even though the sidebar is hidden.

1. I will see whether there is a possibility to configure the sidebar width. I will also see whether there is interest in the Hypothesis community to help with this issue.

This could mitigate 2.

Regarding the necessity of an account with Hypothesis: It is true that you need an account. But I'd hope that's not blocking as the same, I think, is true for Disqus.

With Disqus, you can read the comments, and if configured, post with a guest account. This means that the functionality is essentially available to non-Disqus users. With Hypothesis that doesn't seem to be the case which IMHO greatly reduces the benefit.

Regarding the sidebar open on page load configuration: I agree with you that it hides the table of contents, but this was just to show that it's possible and for me it also showed that there is this slight overlap of the sidebar with the contents to the left. This could be solved via some CSS tweaks, right?

What would you want to tweak?

[jfix]

Just as to the need of a Hypothesis account:

It seems like you should be able to see public annotations and notes from other users, even when not logged in:

So, that makes it kind of comparable to Disqus again. ;-)

Also, the tool is open-source and therefore can be used in any kind of scenario or environment. By default, the service provided by Hypothesis itself is preconfigured; but nothing should prevent a website publisher to maintain their own service.

[squidfunk]

Didn't know that, that's great! If the mobile navigation issues could be resolved, we should be a large step closer towards integration.

[jfix]

I was about to send a request to the Hypothesis folks, but was wondering about the current behaviour:

Would you have an explanation for why the Material hamburger button thinks it has been tapped when in reality I've tapped the Hypothesis close button? A question of event handling?

[squidfunk]

Hmm, no, not really. We removed FastClick some time ago which from my current knowledge would have been the only possible explanation. You could try to integrate Hypothesis to another site with a similar mechanic (= hamburger menu) and see if it exhibits the same behavior.

[jfix]

I just left this comment on the public Slack channel of the Hypothesis project:

Hi there, I seem to have come across a usability issue when using the hypothesis sidebar on mobile devices. Would this be something I report here or on Github? (Not sure a Saturday evening in the summer is the best time to post this... ;-) )

More specifically, when the sidebar (using the classic theme) is open, its close button in the left top corner covers the underlying page's hamburger button. When I click the sidebar close button the sidebar does close, but for some reason the click/tap event is passed through to the underlying hamburger button and opens the page's menu which, of course, is not desirable.

A demo of the issue can be seen here (I only used the Chrome debug tools to emulate mobile devices): https://jfix.github.io/mkdocs-hypothesis-test/vol1/introduction/S2/

The background context here is that I'm discussing with the maintainer the integration of a Hypothesis extension into MkDocs' Material theme (https://squidfunk.github.io/mkdocs-material/), a really great static site generator.

Of course, as a workaround I could use the clean theme which positions the close button not at the top but a bit further down, but
a) I want to not open the sidebar by default but can't find an 'open sidebar' button when using the clean theme, and
b) it's a workaround, not a solution. ;-) I'd like to leave the theme decision with the website publisher, not force them to use one over the other because of this.

[jfix]

Added above comment to an existing ticket: https://github.com/hypothesis/product-backlog/issues/94#issuecomment-507346194

[squidfunk]

Any update?

[squidfunk]

Closing for housekeeping. We will re-open this issue if there's progress.

[jfix]

Sorry for the delay. We've invested some time to understand the problem and it comes clearly from the Hypothesis code (nothing to do with mkdocs-material). It also became clear in discussion with Hypothesis project members that the current mobile version of the sidebar is far from optimal.

Therefore, our thinking is that we should simply not show the sidebar on mobile. But this would mean that the script injection should be dependent on the viewport size. And, of course, we cannot do this in the Hypothesis code.

This in turn led us to wonder whether it would be possible to envisage an extension that allows the injection of Javascript code in the header at build time. Like so, to inject the contents of a Javascript file in a <script> element inside the header (or at the end of the body):

generic-javascript:
    - file: 'path/to/javascript/that/needs/to/be/injected.js'
    - placement: header | body

I guess other options could be considered. As this is no longer on topic, if you think it's worthwhile, I can create a new issue with this suggestion.