9

In my Readme.MD markdown file I want to create Table of Contents (for Github). [TOC] (generated by Typora) doesn't show on Github. It shows like [TOC]. Some of my headings contain characters like a dot or a comma. Is there any way to link to these headings?

I tried almost everything I think, such as: [app.js File](#app.js-file), [app.js File](#app-js-file), [app.js](#app--js-file), [app.js](#app\.js-file), [app.js](#appjs-file). Nothing works.

Here is an example:

Table of contents:
[app.js](#app-js)
[script.js](#script.js)
[One, two, three](#one,-two,-three)

# app.js File
Some text

# script.js File
Some text

# One, two, three
Some text

P.S. Some people are talking about creating HTML-anchors (named), but how/where do you write them in your MD-file (in case it is the solution). Could you explain it please (I couldn't find any solution on the internet).

LowLevel
  • 1,085
  • 1
  • 13
  • 34

3 Answers3

11

If you mouse over the header you want to link to in the rendered content you should see a link icon appear. Mouse over that icon to see what it's linking to, and use that as your target. I think you'll find the links named

  • appjs-file
  • scriptjs-file
  • one-two-three

This answer points to some logic that may drive link naming but I haven't been able to confirm.

As a side note, Markdown is designed to be easily read even in its raw form. I strongly recommend adding a space between the header hashes and header text and a blank line between the header and its content, e.g.

# app.js File

Some text

Some Markdown processors will require one or both of these to render properly.

ChrisGPT was on strike
  • 127,765
  • 105
  • 273
  • 257
  • Thank you for your answer, but this doesn't work (on Github) unfortunately. – LowLevel Dec 21 '18 at 20:11
  • 1
    Did you try the first part? Mouse over the rendered content to see what links are generated and use those in your target. Note that this _does_ work on GitHub's Gists (I verified before posting). – ChrisGPT was on strike Dec 21 '18 at 20:14
  • If I let Typora to automatically generate TOC (Table of Contents; which is not readable on github), it creates complex HTML DOM-view of specific structure. "Mouse over" does/shows nothing, but if I right-click and Inspect it, it shows the elements, but this way you cannot solve it, I guess: See the screenshot: https://imgur.com/a/j7hgStY – LowLevel Dec 21 '18 at 20:21
  • Wait, what? What does Typora have to do with this? I thought you wanted to manually link to a heading on GitHub? – ChrisGPT was on strike Dec 21 '18 at 20:29
  • Look, typora can edit Readme.md files. So, in Typora I generated TOC, but when I uploaded the Readme file to Github, it didn't show. Instead I saw `[TOC]` text (no content, no hyperlinks, nothing). I decided to edit my Readme.MD on Github. I cannot create hyperlinks (named anchors) inside my Table of Contents now, which is linked to my headings (that contain dots/commas). – LowLevel Dec 21 '18 at 20:32
  • Because you told me to mouse over the content to see what links are generated. No links are generated. I create links manually, and I don't know how to create this sort of links: I mean links, that are automatically linked to headings containing dots/commas. – LowLevel Dec 21 '18 at 20:33
  • Right. So you're manually creating a table of contents. That's what I thought. So Typora is irrelevant, right? – ChrisGPT was on strike Dec 21 '18 at 20:33
  • Not the _Typora_ links. The _headings you're trying to link to_. There should be a link icon when you mouse over a heading. Mouse over that link icon. – ChrisGPT was on strike Dec 21 '18 at 20:33
  • Yes, Typora seems to be irrelevant. – LowLevel Dec 21 '18 at 20:34
  • That's why I posted my question here. – LowLevel Dec 21 '18 at 20:34
  • Ok ok ok. Now I understand what you are talking about.... Thank you so much. It works!!! – LowLevel Dec 21 '18 at 20:36
  • 1
    Glad to hear it! I'll update my answer to clarify that point. – ChrisGPT was on strike Dec 21 '18 at 20:37
  • 1
    I just didn't know links are automatically generated for headings. And all I have to do is to create hyperlinks (anchors) linked to these named-anchors (links). – LowLevel Dec 21 '18 at 20:38
3

Question 1

Is there any way to link to these headings(that contain punctuation marks)?

Yes. Drop all the punctuation marks and replace the spaces with hyphens. This works for Github but with some other markdown editors like for example at hashnode.com, you have to replace the punctuation marks with hyphens.

In your example above, I hadn't linked the full titles. That's why some didn't work. To fix the example you gave:

Table of contents:
[app.js](#appjs-file)
[script.js](#scriptjs-file)
[One, two, three](#one-two-three)

# app.js File
Some text

# script.js File
Some text

# One, two, three
Some text

Question 2

Some people are talking about creating HTML-anchors (named), but how/where do you write them in your MD-file (in case it is the solution)?

You add the HTML anchors right next to the heading you would like to link to on the same line. The link you provide in the table of contents should match the name of anchor in the heading but drop the hash.

Here's an example:

Table of contents:
[app.js](#app-js-file)
[script.js](#script-js-file)
[One, two, three](#one-two-three)

# app.js File <a name="app-js-file"></a>
Some text

# script.js File <a name="script-js-file"></a>
Some text

# One, two, three <a name="one-two-three"></a>
Some text

Here's a Github Gist to demonstrate that it works on Github.

the_coops
  • 86
  • 5
1

In GitHub, if you hover over the section title words, a link icon appears to the left of the section title words. If you hover over the link icon , the URL for the webpage you're on appears at the bottom of the page (i.e., github.com/username/.../README.md). If you continue hovering over the link icon for a few seconds, that link then includes the appended section link (i.e., github.com/username/repo/edit/main/README.md#appjs-file).

Solution:

Table of contents:
[app.js File](#appjs-file)
[script.js File](#scriptjs-file)
[One, two, three](#one-two-three)

# app.js File
Some text

# script.js File
Some text

# One, two, three
Some text
carot3
  • 49
  • 2