Link to a line Markdown file on GitHub

As it is currently not possible, I take the next best option: use blame and then highlight the lines, e.g. https://github.com/rails/rails/blame/master/guides/source/configuring.md#L166


Now Supported with ?plain=1

Announced on June 30, 2021, there is now a parameter to disable markdown rendering:

Appending ?plain=1 to the url for any Markdown file will now display the file without rendering. As with other code files, it will also show line numbers, and can be used to link other users to a specific line or lines. For example, appending ?plain=1#L52 will highlight line 52 of a plain text Markdown file.

It sounded like you might want to use line numbers to link to a point in the rendered document. That is still possible, nor is it a standard feature of markdown renders to add line number anchors like that.


For the benefit of the reader: The long answer is yes, it is difficult, but possible.

GitHub allows to inline permalinks to the text portion of Markdown files

However there seems currently to be no way to create such permalinks directly, you must manually create them. As follows:

  • Display the markdown document
  • Above the document on the right click on the shortened SHA of the document
    (you can use "History" and the commit in question as well)
  • The commit's diff is shown.
  • Above the commit on the right click on the the 3 dots ... and select "View file"
  • Now the Mardown is presented again however it is the permanent variant.
  • Above the document on the right click on "Blame"
  • Scroll down to the lines which contain the Markdown representation of the text to cite
  • Select the line or lines in question
  • Copy the URL from the address bar of the browser
  • Paste the URL into the issue etc.
  • This step is only needed within issues: In the URL replace /blame/ by /blob/

In the preview of the Issue you will see the expected direct citing of the text portion of the Markdown.

Drawback of the /blob/-variant

If you click on the URL, you see the full Markdown in the browser, the text portion is not marked as expected.

This is a limitation on how GitHub handles those URLs.

Drawback of the /blame/-variant

It is plain unreadable because of all those annotations and non-rendering of the Markdown.

Example

Note that I had to clone this example to be able to create an issue:

https://github.com/hilbix/learn.github.com/blob/gh-pages/README.md

  • Click on the SHA

https://github.com/hilbix/learn.github.com/commit/38034b3aee7f4fb7f46e94b3f9c2b3d3554291ba

  • "View File"

https://github.com/hilbix/learn.github.com/blob/38034b3aee7f4fb7f46e94b3f9c2b3d3554291ba/README.md

  • "Blame"

https://github.com/hilbix/learn.github.com/blame/38034b3aee7f4fb7f46e94b3f9c2b3d3554291ba/README.md

  • Mark some lines

https://github.com/hilbix/learn.github.com/blame/38034b3aee7f4fb7f46e94b3f9c2b3d3554291ba/README.md#L20-L23

  • Change the URL

https://github.com/github/learn.github.com/blob/38034b3aee7f4fb7f46e94b3f9c2b3d3554291ba/README.md#L20-L23

  • Paste this URL into some issue

Result: https://github.com/hilbix/learn.github.com/issues/1

This was entered into the issue:

https://github.com/hilbix/learn.github.com/blob/38034b3aee7f4fb7f46e94b3f9c2b3d3554291ba/README.md#L20-L23

see https://stackoverflow.com/a/57202063/490291

This renders to something like

learn.github.com/README.md

Lines 20 to 23 in 38034b3
    $ git clone https://github.com/github/learn.github.com
    $ cd learn.github.com
    $ script/bootstrap
    $ jekyll --server

see https://stackoverflow.com/a/57202063/490291

Here is the full HTML of the issue created (sorry, I did not manage to copy the CSS, too):

<td class="d-block comment-body markdown-body  js-comment-body">
          <p></p><div class="border rounded-1 my-2">
  <div class="f6 px-3 py-2 lh-condensed border-bottom bg-gray-light">
    <p class="mb-0 text-bold">
      <a href="https://github.com/hilbix/learn.github.com/blob/38034b3aee7f4fb7f46e94b3f9c2b3d3554291ba/README.md#L20-L23">learn.github.com/README.md</a>
    </p>
    <p class="mb-0 text-gray-light">
        Lines 20 to 23
      in
      <a data-pjax="true" class="commit-tease-sha" href="/hilbix/learn.github.com/commit/38034b3aee7f4fb7f46e94b3f9c2b3d3554291ba">38034b3</a>
    </p>
    </div>
    <div itemprop="text" class="blob-wrapper blob-wrapper-embedded data">
    <table class="highlight tab-size mb-0 js-file-line-container" data-tab-size="8">

        <tbody><tr class="border-0">
          <td id="L20" class="blob-num border-0 px-3 py-0 bg-white js-line-number" data-line-number="20"></td>
          <td id="LC20" class="blob-code border-0 px-3 py-0 bg-white blob-code-inner js-file-line"> <span class="pl-s1">$ git clone https://github.com/github/learn.github.com</span> </td>
        </tr>

        <tr class="border-0">
          <td id="L21" class="blob-num border-0 px-3 py-0 bg-white js-line-number" data-line-number="21"></td>
          <td id="LC21" class="blob-code border-0 px-3 py-0 bg-white blob-code-inner js-file-line"> <span class="pl-s1">$ <span class="pl-c1">cd</span> learn.github.com</span> </td>
        </tr>

        <tr class="border-0">
          <td id="L22" class="blob-num border-0 px-3 py-0 bg-white js-line-number" data-line-number="22"></td>
          <td id="LC22" class="blob-code border-0 px-3 py-0 bg-white blob-code-inner js-file-line"> <span class="pl-s1">$ script/bootstrap</span> </td>
        </tr>

        <tr class="border-0">
          <td id="L23" class="blob-num border-0 px-3 py-0 bg-white js-line-number" data-line-number="23"></td>
          <td id="LC23" class="blob-code border-0 px-3 py-0 bg-white blob-code-inner js-file-line"> <span class="pl-s1">$ jekyll --server</span> </td>
        </tr>
    </tbody></table>
  </div>
</div>
<p></p>
<p>see <a rel="nofollow" href="https://stackoverflow.com/a/57202063/490291">https://stackoverflow.com/a/57202063/490291</a></p>
      </td>

Tags:

Github

Recent Posts