Cross Reference in Markdown

[Kray-G]

Hi there,

I would like to talk about cross reference in Marp.

At first, we can jump to the slide that we want to go to with like [Text](#2) when we want to go to the slide number 2. But we will often face the page number has been changed even though we don't hope it. That's why I added the tag style for cross reference between slides like the following.

section a.cref {
  display: block;
  position: absolute;
  top: 0px;
  left: 0px;
  z-index: auto;
}

And it works very good as I expected with this.

---
# Subject of the page <a class="cref" id="thepage"></a>

...

[Go to The Page](#thepage)

But I feel it's not beautiful because the tag is occupied on the document and it's not related to the actual content of the document. Generally, we all who write any markups should not think about the shape and how tags should be used, and we all should focus on the content itself. If we follow that principle, we have to make it more smart.

So I have some questions.

• Do you have any other solution for this purpoe of cross reference?
• If you don't have, is it possible to add some solution? For example, adding some directive like <!-- _cref: idname --> and using it with the link like [Text](#idname), or something.

Cheers.

[yhatt]

See also: https://github.com/orgs/marp-team/discussions/161#discussioncomment-5627844

In Markdown documents, it's common to use automatically generated anchors from the heading content to jump to specific headings. In Marp as well, you can use such anchors without having to write HTML and CSS:

# Subject of the page

---

[Go to the page](#subject-of-the-page)

You can reference the page that including the specified heading by the link.

In addition, it's also possible to suggest the anchor names generated from the headings by using VS Code. (This feature is provided by the Markdown Language Server in VS Code, not Marp for VS Code extension)

This approach is smart enough to eliminate the need for using <a> HTML tags, and compatible with other common Markdown processors.

The Marp Markdown format also places importance on cross-compatibility with other Markdown processors. Adding the directive like <!-- _cref: ... -->, Marp's unique syntax, would decrease compatibility with other Markdown processors. Therefore, we have not considered that a smart approach. Using HTML tags is the right approach also as defined in the CommonMark spec.

[Kray-G]

Thanks for your helpful answer. That is how nice information actually. But there are 2 problems on your answer.

• First, it doesn't work with Japanese characters like # リンク and [リンク](#リンク). I tried it some times but it didn't work at all.
• Second, when I used English, it worked very well but it didn't jump to the top of the slide page, and it just jumped to the place where a header text existed. When you look at my style sheet, you will find the element of the class of cref for <a> tag is set to the top of the target page at the locaion of (0, 0). It means that you will jump to the top of the target page when you click it.

I understand your opinion that we shouldn't do the different way from the standard way. But I couldn't find some better answers on it.

Anyway, for now, I will use the reference tag that I have made, and if you have some better solution, plase let me know.

Thanks in advance.

[Kray-G]

It means that you will jump to the top of the target page when you click it.

Let me explain a little bit. This means you can see all of the slide page that you want to see from the top to the bottom after jumping it when you click the link. If we used the automated anchor tag of the header, you couldn't see the top of that slide at least and you could see only a part of that slide because the header would be at the middile or a little upper side of the middle of the slide instead of the top of it.

That's why it would be nice if you could take care of this issue.

That's what I wanted to say.

Thanks.

[yhatt]

it doesn't work with Japanese characters like # リンク and [リンク](#リンク). I tried it some times but it didn't work at all.

That cannot reproduce at least for me. The simple case like [リンク](#リンク) is working well in VS Code preview, the exported HTML, and PDF.

video.mov

it didn't jump to the top of the slide page, and it just jumped to the place where a header text existed.

That should not be a problem because the slide would be presented one by one pages when doing the actual presentation by PDF/HTML. (See above video)

[Kray-G]

It looks so great! But I am sorry I can't try it right now. I'll try it next week and let you know the result as soon as I've got it.

Thanks!

[Kray-G]

As you said, I conformed it worked well in PDF. Thanks so much. Only with a preview, the page didn't set to the top, but it's not a problem.

With regard to Japanese characters, it worked with a simple sentence but it didn't work with a complex one. I feel it probably has a impact about some rules when creatng a link of a header.

I did some try and I found one thing about the difference between a header text and its link name. For example, if I used '～' of a wave character in the header text, it was ignored in the link.

# ～仕様の見出し
...
[～仕様の見出し](#～仕様の見出し) ... it doesn't work.
[～仕様の見出し](#仕様の見出し) ... it works!

Additionally, you're right and almost all cases I can find the anchor tag by using Markdown language server's suggestion. But if I used ～ at the head of the sentence, it was so difficult to find it because I didn't start writing 仕様 without ～. I feel it's a rare case so it's not a problem for almost all cases, but it would be nice if we could know what anchor tag was used on demand. Do you have any solution on that?

Thank you so much for your kind answers.

[yhatt]

I did some try and I found one thing about the difference between a header text and its link name. For example, if I used '～' of a wave character in the header text, it was ignored in the link.

Marp (Core), VS Code, and Markdown Language Service follow GitHub's slugifier, the conversion rule to the anchor name. It strips some known punctuator symbols while converting to the anchor, that is including the full-width tilde ～.

https://github.com/microsoft/vscode-markdown-languageservice/blob/3997f638a8700ba8c2eb7ce4859db73589b75e90/src/slugify.ts#L26-L39

it would be nice if we could know what anchor tag was used on demand. Do you have any solution on that?

When you are using VS Code preview, you can inspect the heading elements to find the actual anchor assigned by the id attribute. Choose Toggle Developer Tools from the command palette or "Help" menu, and inspect the heading element in the "Element" panel of the developer tools.