proposal: crosslinks

[eshellman]

PR #5525 introduces section-to-section crosslinks so that users looking for Angular books will find them whether they are looking for Angular or AngularJS.

This issue asks the community:

• Is this a good way to make this repo more useful?
• Should crosslinks look different from what is being done in #5525?
• When should we add a crosslink? Should Android be crosslinked with Java? When should crosslinks should NOT be added? (we need guidelines)
• how does this relate to #5249 (dealing with language agnostic books)

[davorpa]

At a glance.... the proposal syntax is...

All crosslinks starts with > :information_source: and uses horizontal ellipsis … as delimiter between crossed sections and it alphabetized text. This markup goes between heading and it listing first item preseving the 1 whitespaces rule on all of them.

One way reference:

### Heading A

> :information_source: See also … [Heading B](#heading-b)

* [Awesome book in A](https://library.example.com/awesome-book-a) - creator 1, creator2 et al. (FORMAT) (platform) (*notes*)

Two sides reference:

### Heading A

> :information_source: See also … [Heading Z](#heading-z)

* [Awesome book in A](https://library.example.com/awesome-book-a) - creator 1, creator2 et al. (FORMAT) (platform) (*notes*)

### Heading Z

> :information_source: See also … [Heading A](#heading-a)

* [Awesome book in Z](https://library.example.com/awesome-book-z) - creator 1, creator2 et al. (FORMAT) (platform) (*notes*)

Multireference: separate each one by a comma

### Cabecera A

> :information_source: Véase también … [Cabecera M](#cabecera-m), [Cabecera Z](#cabecera-z)

* [Un recurso alucinante en A](https://libros.example.com/libro-a) - creator 1, creator2 et al. (FORMAT) (platform) (*notes*)

### Cabecera M

> :information_source: Véase también … [Cabecera A](#cabecera-a)

* [Un recurso alucinante en M](https://libros.example.com/libro-m) - creator 1, creator2 et al. (FORMAT) (platform) (*notes*)

### Cabecera Z

* [Un recurso alucinante en A](https://libros.example.com/libro-a) - creator 1, creator2 et al. (FORMAT) (platform) (*notes*)

I hope this snippets helps to understand what is the idea.

[eshellman]

did you try having the crosslinks below the list?

[davorpa]

did you try having the crosslinks below the list?

I could try. Let me a bit to prepare a demo in my deploy with Angular resources.

Only one note: I prefer at top if lists are long because is more intuitive and don't need scroll

/labelthis: proposal, discussion

[davorpa]

did you try having the crosslinks below the list?

@eshellman, it works fine at bottom too. No problems with linter if rule 1-0-2 is respected.

Now the rule will be 1-(0-1)?-0-2 at top, or 1-0-(1-0)?-2 if placed at bottom :laughing:

Here the example in both sides I promised (javascript section): DEPLOY and CODE BRANCH

Only one note: I prefer at top if lists are long because is more intuitive and don't need scroll

[eshellman]

I was thinking that if we separate out the "language agnostic" section to a separate page, we might need more than one crosslink, and you don't want people scrolling through crosslinks to get to the listings. I looked in a cookbook with many "see also" listings in the index - it puts the cross links in the topic heading itself.

[davorpa]

Well-thinking!

But If crosslink is attached after section title, auto TOC is broken in markdown because generated ids change according to heading text.

### Heading A (:information_source: … [Heading B](#heading-b))

produces an id anchor heading-a-information-source-heading-b for Heading A instead of a merely heading-a

Therefore the multireference variant: one after other comma delimited.