{"action":"created","issue":{"url":"https://api.github.com/repos/azerupi/mdBook/issues/58","labels_url":"https://api.github.com/repos/azerupi/mdBook/issues/58/labels{/name}","comments_url":"https://api.github.com/repos/azerupi/mdBook/issues/58/comments","events_url":"https://api.github.com/repos/azerupi/mdBook/issues/58/events","html_url":"https://github.com/azerupi/mdBook/issues/58","id":108012105,"number":58,"title":"Have a page table of contents option available","user":{"login":"mdinger","id":4156987,"avatar_url":"https://avatars.githubusercontent.com/u/4156987?v=3","gravatar_id":"","url":"https://api.github.com/users/mdinger","html_url":"https://github.com/mdinger","followers_url":"https://api.github.com/users/mdinger/followers","following_url":"https://api.github.com/users/mdinger/following{/other_user}","gists_url":"https://api.github.com/users/mdinger/gists{/gist_id}","starred_url":"https://api.github.com/users/mdinger/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mdinger/subscriptions","organizations_url":"https://api.github.com/users/mdinger/orgs","repos_url":"https://api.github.com/users/mdinger/repos","events_url":"https://api.github.com/users/mdinger/events{/privacy}","received_events_url":"https://api.github.com/users/mdinger/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/azerupi/mdBook/labels/Discussion","name":"Discussion","color":"13a957"}],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":2,"created_at":"2015-09-23T21:38:37Z","updated_at":"2015-09-23T22:39:21Z","closed_at":null,"body":"One thing the rust book does a lot is have really long pages with many subsections in it. For example, see the [modules page](http://doc.rust-lang.org/nightly/book/crates-and-modules.html). One fix for this is to avoid having long pages but I'm not sure that is a good long term strategy that you can impose on users.\r\n\r\nA better fix is to have an in-page TOC on every page (perhaps enabled with a flag). The best example I've seen of this is [MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/padding) where both left and right contents collapse when the page is thin. The right side floats and follows you down the page which I think is really nice. Even collapsed though, the TOC moves to the top where it can be vertically collapsed as well. I think it's a really nice design.\r\n\r\nTo accommodate that, you probably would have to make adjustments to the content page width and perhaps to font size. mdBook content and the left sidebar is currently on the wide side though it looks good for as it is for now."},"comment":{"url":"https://api.github.com/repos/azerupi/mdBook/issues/comments/142750364","html_url":"https://github.com/azerupi/mdBook/issues/58#issuecomment-142750364","issue_url":"https://api.github.com/repos/azerupi/mdBook/issues/58","id":142750364,"user":{"login":"mdinger","id":4156987,"avatar_url":"https://avatars.githubusercontent.com/u/4156987?v=3","gravatar_id":"","url":"https://api.github.com/users/mdinger","html_url":"https://github.com/mdinger","followers_url":"https://api.github.com/users/mdinger/followers","following_url":"https://api.github.com/users/mdinger/following{/other_user}","gists_url":"https://api.github.com/users/mdinger/gists{/gist_id}","starred_url":"https://api.github.com/users/mdinger/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mdinger/subscriptions","organizations_url":"https://api.github.com/users/mdinger/orgs","repos_url":"https://api.github.com/users/mdinger/repos","events_url":"https://api.github.com/users/mdinger/events{/privacy}","received_events_url":"https://api.github.com/users/mdinger/received_events","type":"User","site_admin":false},"created_at":"2015-09-23T22:39:21Z","updated_at":"2015-09-23T22:39:21Z","body":"I'm not opposed to them dividing it up but they may never divide it up. It depends on if they decide it's worth the effort, if it would make it better, and so on. As it is, if they decided to not move to a deeper structured document then users are stuck without a page TOC because the tooling doesn't support it. Supporting it at least (optionally) makes life better for users even if the developers decide to be lazy.\r\n\r\nAlso, the rust docs are kinda okay which means they might have issues but they'll come up less frequently because they're workable. People point out issues when they're really bad more than when they're decent.\r\n\r\nOne issue with dividing it up is they don't have search built-in, but they do have firefox search built in so really long pages are kinda workable. If the docs become search enabled then this becomes less of an issue though.\r\n\r\nThe problem with deeply nested TOC is that while the short examples are great, it's difficult to discover the precise example you desire. Doing it well basically requires good search-ability and really good cross-linking.\r\n\r\nFor example, rustbyexample has 20 chapters with probably an average of 5 subchapters per chapter, so an estimate of 100 pages to look through. Probably more. So if you're looking for info on `ref`, you search ref and click on [one](http://rustbyexample.com/flow_control/match/destructuring/destructure_pointers.html) of the [two](http://rustbyexample.com/scope/borrow/ref.html) `ref` pages. If what you're looking for isn't in one of those two pages (supposing the answer you're looking for is there somewhere) you basically have to skim everything from top to bottom. The rust book might do a little better by getting you to one of the 5 pages that cover the topic.\r\n\r\nAnother thing is some people actually [prefer](https://internals.rust-lang.org/t/rustdoc-mockup-for-including-more-structured-content/2540/2) big pages so they would probably consider a page table of contents as an advantage.\r\n\r\nBasically though, it's kind of complicated but you're probably trying to cover some middle ground so that users who write long pages get good docs, users who write short pages get good docs, and users who don't care get good docs."}}