HTML anchors as sections in sidebar

[jorisvanzundert]

Hi,

(Apologies for being a bit verbose.)

Is it possible to have section headers in the sidebar that are links to section anchors? Thus, section headers that point to e.g. "/mybook/chapter_002#a-particular-section. (Each # header in .md becomes an anchor.)

I tried a workaround by using simply external: true, but this fails because _prepare_toc() errors out on the hashtag. Besides, it is of course not really an external link.

I have a solution that requires trivial changes to build.py, and adds an option internal_anchor: [true|false]. But this does not check validity of the anchor or anything, which might be the more proper way (not sure, there's of course also no checking external links).

The reason I ask is that I wrote a conclusion that has three small subsections. Publishing them as different sections on different pages of the book, came across very counter natural/intuitive. But the one page integrated conclusion can not have links to its subsections in the sidebar with Jupiter Book's current idea of document—which I'd like.

Happy to submit a PR if this fits the concepts of document here, but I thought better to discuss it beforehand.

Thanks, all best --Joris

[choldgraf]

Interesting - I think this could be useful for folks that want internal links...what if there were an extra field that was a string, as opposed to a bool. E.g.:

- title: My title
  url: path/to/notebook
  anchor: my-header-anchor

and if there were an anchor defined, it'd automatically append the #my-header-anchor at the end of the link on the page. Would that be a reasonable pattern for you?

[jorisvanzundert]

Yep, that would work neatly. Should I try and submit a PR, somebody else?

[choldgraf]

I'd be happy to look over a PR if you put one together! Can you make sure to add a test as well? :-)

[jorisvanzundert]

Sure, np, will be a day or two due to business, but expect a PR soonish :)

[rossbar]

Is this still a feature of interest? If so I'm happy to take a run at it; however, I think there are actually two different features being proposed here.

If I understand correctly, the original feature request is something along the lines of autogenerating anchor links in the sidebar from the headings from a single source file.

The feature proposed in the top comment adds the ability to add an anchor to an entry that is already explicitly specified in the toc.yaml.

I think both are useful features but will require differing amounts of work to implement: I think the second feature (adding the anchor keyword) can be done by modifying the sidebar.html liquid template without touching the jupyter-book machinery itself. I submitted draft PR #456 to illustrate how I think this might be achieved.

The original feature (if I understood it correctly) I think would involve a bit more than modifying the sidebar template. I'm happy to pursue it as well (I do think it would be a nice feature) if others think there is value in it.

[jorisvanzundert]

Just to be clear: I didn't mean so much auto-generation, although that could be nice. However, the way the top comment describes the feature is what I was aiming/hoping for. (The risk of auto-generation could be that too many internal links are generated, so you'd need an option to control that, more fluff, etc.)

[rossbar]

Thanks for the clarification, that's a good point that I hadn't considered about auto-generation.

The approach in #456 can be used to achieve the behavior you describe above. If you had something like:

# Conclusion
This is my conclusion chapter, stored in `/content/path/to/conclusion.md`

## Point number one
I'd like this section to have its own internal link in the sidebar

## Point number 2
And this section as well

You could achieve the desired sidebar behavior with the following entry in toc.yaml

- url: /path/to/conclusion
  expand_sections: true
  - title: Point number one
    url: /path/to/conclusion
    anchor: Point-number-one
  - title: Point number 2
    url: /path/to/conclusion
    anchor: Point-number-2

Does this sound like I've understood correctly?

[jorisvanzundert]

Yep, that would totally work for me.

[himanshu007-creator]

is this issue resolved now?

[zothsu]

This issue appears to be resolved

https://github.com/executablebooks/jupyter-book/pull/456