Skip to content

Latest commit

 

History

History
55 lines (32 loc) · 2.9 KB

lists-on-github.md

File metadata and controls

55 lines (32 loc) · 2.9 KB

Known Issues: Lists in GitHub Repos

Note: This issue may only affect you or your readers

  1. when navigating GitHub previews of Markdown files within a GitHub repository
  2. when navigating from a list item generated with the listOf config option to a link target that requires the browser to scroll the link target into the visible viewport

The issue is: *the browser may not scroll the link target into the visible viewport as expected.

Reproduction of the Issue

Let's imagine such a GitHub repository. It has a file README.md that has a lot of text and some addressable HTML element <cite> quite at the bottom of that page:

*README.md*

~~~md
... lot's of text here...
<cite id="some-magazine" class="citations" >Some Magazine Title</cite>
~~~

  • ...to have a file list.md generated using listOf with class: "citations":

    list.md

    ## [Citations](#my-list)

*   [Some Magazine Title][2]

[2]: ./README.md#some-magazine

Then you browse the repository in the web browser enjoying GitHubs preview of Markdown files in the repo. You would like to navigate from list.md to ./README.md#some-magazine by clicking the list item link generated by glossarify-md. You'd expect your browser to scroll to the link target quite at the bottom of page.md but it doesn't!

Root Cause

GitHub sanitizes Markdown files (see GFM 🌎 Sect.1.1) before HTML-rendering them within repository previews. It does so to safeguard GitHub users from evil repository owners who attempt to embed scripts and harmful content into markdown and make that content execute in a victims browser while it browses GitHub. To prevent that GitHub only allows for a small subset of the most commonly used and safe HTML tags and strips others. <cite> is among those that are stripped. The browser therefore can't find that element in the Markdown preview and consequently can't scroll to it.

Workaround

If you care for navigability in GitHub repositories only use HTML tags like <span> or <a> that aren't stripped in GitHub repository previews.

Note that this is a limitation of GitHub's repository preview renderer only! It is not a bug in glossarify-md and once you use a static website generator to generate HTML files from Markdown in order to host them on GitHub Pages 🌎 or your own webserver, things will work just fine. It's just when navigating GitHub previews of Markdown files where things may not work as you would expect them to do.