Improve big-file usability. Add "Return to Top" Links?

[minelarka14]

As the content in a single file is huge, scrolling to the top seems to be a hassle. Would it be possible to add "Return to the top" links after every subtopic that make navigating the files alot easier? I wouldn't mind doing this.

[eshellman]

we could also think about ways to break it into smaller chunks. we could do language agnostic and language specific. if we do links to the index, we probably don't want them after every topic.

Comment from the community will be appreciated!

[kadhirash]

Having it at the end of every single topic does seem excessive, but a workaround could be #4588.

If the files were in separate directories by language specific, for example, then it'd be much less to scroll through and return to top wouldn't be needed!

[SethFalco]

I don't have a strong opinion on this issue, I just wanted to drop by something interesting I noticed on another repo. (If anything, I'm probably with @kadhirash and think having a link on every topic would be excessive.)

I just wanted to note though, it doesn't look like it's unfeasible, another repo took such an approach in the README.

At the end of each heading, they add an up-arrow which goes to the top of the page. - https://github.com/chicagoruby/MongoDB_Koans

Hypothetically, if this was to be done as described, seems like a viable solution.

[borgified]

control + up arrow or command + up arrow (if you are on mac) will take you to the top of any webpage

[minelarka14]

I think that this would greatly improve readability while still retaining minimalism, is it alright if I create a PR to add this?

[eshellman]

I took a look at that repo, the source files are "rdoc" rather than "md". How do you propose that we implement it? How will it be maintained? will it play nice with our linter?

[ianchanning]

I think you should be consistent with other awesome lists. I don't remember ever seeing a 'return to top' link. For example the main awesome list is very long, but still has no return links.

I guess this list is longer than others, but it still seems out of place.

The nngroup does recommend it and I guess on mobile it is handy.

However it would be nice if we could find similar examples elsewhere in the awesome list universe

[eshellman]

we've reorganized our files, so now is a good time to make changes.

[SethFalco]

On the side, since this repository recognizes itself as an awesome list on the README, it might be nice to add the awesome topic to it on GitHub.

---

I'll gladly contribute the change, but just want to verify if we really want to do this, and if so, which method.

Looking at the most popular awesome repositories on GitHub with the topic awesome.

• awesome - N/A
• awesome-python - N/A
• awesome-go - N/A
• awesome-selfhosted - ^ back to top ^ under each heading.
• Awesome-Hacking - N/A
• awesome-mac - N/A
• awesome-nodejs - N/A
• awesome-android-io - N/A
• awesome-interview-questions - N/A
• awesome-ios - N/A
• awesome-courses - N/A
• awesome-flutter - N/A
• awesome-cpp - N/A

From here we can see most of the most popular awesome repositories don't actually include back to tops at all despite being massive. I also checked the issues and pull requests and didn't see any demand for a back to top link either.

That doesn't go to say it's undesirable though, just that others don't do it, and there doesn't seem to be a convention among awesome repositories.

Proposals:

Do Nothing (Current)

Just leave the repo as it and close this issue, personally I think it's fine as is anyway.

Java

• Cool Java Resource - Author

Python

• Cool Python Resource - Author

"back to top" under Heading

The same way that awesome-selfhosted does it.

Java

^ back to top ^

• Cool Java Resource - Author

Python

^ back to top ^

• Cool Python Resource - Author

Icon Next to Heading

Similar to the screenshot showed during this discussion. This could be achieved with various icons/emojis though, if we do this, it might be worth thinking which one.

I think if we took this approach, using an emoji would be best since it'll look attractive. We should use the actual character (ie ⤴️) though rather than the GitHub shortcut (ie :arrow_heading_up:) so that it can render correctly outside of GitHub.

• ⤴️ - Nice character that GitHub has an emoji for.
• ⬆ - Alternate character if a straight is preferred over curved.
• ↑ - A normal up arrow character, GitHub doesn't have an emote for this character. (Used in screenshot referenced in discussion.)
• Tonnes of others, I just shortlisted apt candidates.

Java ⤴️

• Cool Java Resource - Author

Python ⬆

• Cool Python Resource - Author

Rust ↑

• Cool Rust Resource - Author

[eshellman]

how would it work if we split the english books list into topics and languages?

[SethFalco]

how would it work if we split the english books list into topics and languages?

My understanding is that the "back to top" links would always send the user back to #index (table of contents), so I don't think the structure of the documents would change anything. (Assuming we did "back to top" the way most sites would handle it.)

By Language ⤴️

Java ⤴️

• Cool Java Resource - Author

By Topic ⤴️

Cloud Computing ⤴️

• Cool Cloud Computing Resource - Author

All ⤴️ link to the index/table of contents.

We could technically do it differently, like instead of implementing "back to top", we could implement "up a level" to take the user to the parent heading. For example, from the h2 (Python) to its parent h3 (By Language). I suspect most users wouldn't expect this behavior, so probably not viable, but figured I'd propose the alternative as it came to mind. (Haven't surveyed.)

By Language ⤴️

Java ⤴️

• Cool Java Resource - Author

Spring Boot ⤴️

• Cool Spring Boot Resource - Author

By Topic ⤴️

Cloud Computing ⤴️

• Cool Cloud Computing Resource - Author

The h5 (Spring Boot) link to the parent h4 (Java), h4 link to the parent h3, and the h3 link to the index/table of contents.

[davorpa]

About put the mark on headings...

It would take care to don't break generated anchors by github markdown / github pages and be synced with TOCs

[davorpa]

Another option could be markdown spoilers:

<details><summary>A very long content....! (:arrow_down: Expand/Collapse)</summary>

  **free-programming-books is awesome.**
  
  > ### By Language [:arrow_heading_up:](#index)
  > #### Java [:arrow_heading_up:](#index)
  > * [Cool Java Resource](https://example.com) - Author

  `markup like blockquote's should even work on github!`

  ![Image](https://user-images.githubusercontent.com/22801583/99295480-c05b5e80-2845-11eb-9215-0b34cf2a29e7.png)

</details>

Seen as Dependabot issues description.

PREVIEW

A very long content....! (:arrow_down: Expand/Collapse)

free-programming-books is awesome.

By Language :arrow_heading_up:

Java :arrow_heading_up:

• Cool Java Resource - Author

markup like blockquote's should even work on github!

Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.

Edit: I'm on Android and seems works well. I'll try to make a branch on my fork testing with helldam english book listing 😆

[SethFalco]

I think spoilers are a nice idea, but last time I was on Android the GitHub app didn't render them. Maybe someone could test it on the Android app and verify if this is still the case?

I can set up Anbox later and try it myself if no one else uses it.

Edit: Reworded the initial statement. Spoilers could be a good idea, but I think the GitHub app will cause issues, though.

[LuigiImVector]

Markdown spoilers are a good idea but maybe would give problems to the free-programming-books-parser and to the new contributors since to make the markdown work within the spoiler you need a white space after the tag:

:arrow_down: Invalid

* doesn't * work

<details><summary> :arrow_down: Invalid</summary>
* doesn't
* work
</details>

:arrow_down: Valid

• doesn't
• work

<details><summary> :arrow_down: Valid </summary>

* doesn't
* work
</details>

---

IMO the best idea is to put an emoji every section in the longer files:

C++ :arrow_heading_up:

### C++ <a href="#index">:arrow_heading_up:</a>

Before creating an implementation pr, we need to figure out if any of these things can create problems with fpb-search @EbookFoundation/f-p-b-search