Enhancement request: Link to a specific heading in a document

[JenniBeadle]

At present links to documents are supported but only to the whole document. It would be nice to link to a specific heading either in the same document or another document.

How to do it in Docusaurus
Docusaurus allows this by adding a code to the (destination) heading {#...} and then including that code in the link.
For example, see https://manual.paratext.org/Training-Manual/Stage-1/OD

In chapter 2 under 2.3 Create a new text layout I have a link to section 2.5
... ≡ Paratext menu, under (Paratext > Open, select several resources, choose to open as Text collection. See [2.5]

Heading 2.5 is coded as:
### 2.5 Open resources in a Text collection {#25}
The link is coded as:
See [2.5] (/Training-Manual/02-Stage-1/2.OD.md#25)
(the link is broken to display the coding)

Note: I have the code without decimal points otherwise it didn't work reliably.

Docusaurus documentation
see https://docusaurus.io/docs/markdown-features/toc#example-subsubsection-1-a-ii for a discussion on setting an explicit heading id.

[andrew-polk]

@JenniBeadle
I've been working on this today.
I have a couple questions.

1. Do you need/want to be able to control what the ID is?
   For example, do you need #25?
   Or is it just as good to have something like #ff612bfc-2d1d-4f86-8dbc-54ca34ae0f38?
2. Do you need the links to work internally in Notion? Or only in Docusaurus?

I don't think I can provide both custom IDs and internal linking in Notion.

So the options I see are:

1. User provides the link ID in Notion the same way as in Docusaurus -- by adding {$my-id}. Notion links to headings will not navigate correctly within Notion.
2. User creates links using the notion system of internal IDs (which look like ff612bfc-2d1d-4f86-8dbc-54ca34ae0f38). Those will flow through to Docusaurus as the IDs to use. Thus the urls will end with that ID rather than something the user can define.
3. Allow for both. If the user supplies an ID, use it. If not, use Notion IDs.

[hatton]

The docu-notion way is that you use Notion links, and it just works. Document writers should not see or care. Is that what #2 means?

[JenniBeadle]

Hi Andrew Thanks for your email. It is good to know you are working on the links. I must admit I am struggling to get my head around Notion. Docusaurus took me back in time to the DOS days. Now Notion, WYSYWG but without enough menus and these blocks that don’t do what I want. I just read a great article <https://www.notion.so/blog/data-model-behind-notion> on the data model behind Notion and have a clearer understanding of blocks and their IDs. So by all means *just use the Notion ID*. I have a few edited comments below. Thanks Jenni *From:* andrew-polk ***@***.***> *Sent:* Thursday, 1 December 2022 8:18 AM *To:* sillsdev/docu-notion ***@***.***> *Cc:* JenniBeadle ***@***.***>; Mention < ***@***.***> *Subject:* Re: [sillsdev/docu-notion] Enhancement request: Link to a specific heading in a document (Issue #20) @JenniBeadle <https://github.com/JenniBeadle> I've been working on this today. I have a couple questions. 1. Do you need/want to be able to control what the ID is? For example, do you need #25? Or is it just as good to have something like #ff612bfc-2d1d-4f86-8dbc-54ca34ae0f38? JB: I don’t need to control the ID. It is “just as good” to have the Notion ID since I don’t have to type it anywhere! 1. Do you need the links to work internally in Notion? Or only in Docusaurus? JB: The goal is certainly for it to work in Docusaurus, but the strength of Notion is the collaboration. So I can envisage that it would be even more useful in Notion when working with multiple authors who may not be aware of other sections. I don't think I can provide both custom IDs and internal linking in Notion. So the options I see are: 1. User provides the link ID in Notion the same way as in Docusaurus -- by adding {$my-id}. Notion links to headings will not navigate correctly *within Notion*. 2. *User creates links using the notion system of internal IDs (which look like **ff612bfc-2d1d-4f86-8dbc-54ca34ae0f38**). Those will flow through to Docusaurus as the IDs to use. Thus the urls will end with that ID rather than something the user can define.* 3. Allow for both. If the user supplies an ID, use it. If not, use Notion IDs. JB: I can’t really imagine a user starting in Notion wanting to specify an ID. It wasn’t something I specifically wanted just what I had to do for Docusaurus. So *option 2* would be best to work towards. Reply to this email directly, view it on GitHub <#20 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AZ5F7HL4M2STGI4VCBLPWX3WK7VBZANCNFSM6AAAAAAR43CKEI> . You are receiving this because you were mentioned.Message ID: < ***@***.***>

[andrew-polk]

The docu-notion way is that you use Notion links, and it just works. Document writers should not see or care. Is that what #2 means?

Yes.
@hatton

[andrew-polk]

@JenniBeadle
Ok, thanks for helping me understand your use case better.

[andrew-polk]

Added in cc93d95 for 0.7.0