Automatically generate per-page table of contents

[andrewdavidwong]

@adrelanos helpfully suggested this in a comment on #1332.

The first idea was to use this, but since we host on GitHub Pages, we can't use plugins.

So the second idea was to use this. I've tried to implement it in every way I can think of, but I can't seem to get it to work. Here's an example attempt.

If anyone else is willing to give this a try, please do.

[marmarek]

It looks like you need also to place that TOC somewhere. Add this after </article>:

<script>$('.post-content').toc()</script>

I've tried to have it after page title (<h1>), but no idea how to do that. Also when that TOC code is placed inside of <article> it doesn't work (at least for me).

[marmarek]

It looks like you need also to place that TOC somewhere. Add this after </article>:

<script>$('.post-content').toc()</script>

I've tried to have it after page title (<h1>), but no idea how to do that. Also when that TOC code is placed inside of <article> it doesn't work (at least for me).

[andrewdavidwong]

It looks like you need also to place that TOC somewhere. Add this after </article>:

<script>$('.post-content').toc()</script>

That works! Thanks, Marek!

[andrewdavidwong]

It looks like you need also to place that TOC somewhere. Add this after </article>:

<script>$('.post-content').toc()</script>

That works! Thanks, Marek!

[adrelanos]

Has it been decided to go back to self hosting? If so, is there an ETA for this? I guess it'll take time. However, with self hosting, the limitations raised by GitHub Pages would not apply.

[adrelanos]

Has it been decided to go back to self hosting? If so, is there an ETA for this? I guess it'll take time. However, with self hosting, the limitations raised by GitHub Pages would not apply.

[marmarek]

However, with self hosting, the limitations raised by GitHub Pages would
not apply.

Yes, you're right. Haven't decided when it will happen.
But for now, JS-generated ToC looks good (will be online soon).

Best Regards,
Marek Marczykowski-Górecki
Invisible Things Lab
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?

[marmarek]

However, with self hosting, the limitations raised by GitHub Pages would
not apply.

Yes, you're right. Haven't decided when it will happen.
But for now, JS-generated ToC looks good (will be online soon).

Best Regards,
Marek Marczykowski-Górecki
Invisible Things Lab
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?

[andrewdavidwong]

Has it been decided to go back to self hosting? If so, is there an ETA for this? I guess it'll take time.

I didn't realize that ITL was considering going back to self-hosting (or maybe I just forgot). Any particular reason ITL wants to do that? Saving money by hosting for free on gh-pages seems like a big benefit, and it doesn't seem to be holding us back (not being able to use plugins is very minor, IMHO).

[andrewdavidwong]

Has it been decided to go back to self hosting? If so, is there an ETA for this? I guess it'll take time.

I didn't realize that ITL was considering going back to self-hosting (or maybe I just forgot). Any particular reason ITL wants to do that? Saving money by hosting for free on gh-pages seems like a big benefit, and it doesn't seem to be holding us back (not being able to use plugins is very minor, IMHO).

[marmarek]

On Sun, Oct 25, 2015 at 04:07:26PM -0700, Axon wrote:

Has it been decided to go back to self hosting? If so, is there an ETA for this? I guess it'll take time.

I didn't realize that ITL was considering going back to self-hosting (or maybe I just forgot). Any particular reason ITL wants to do that? Saving money by hosting for free on gh-pages seems like a big benefit, and it doesn't seem to be holding us back (not being able to use plugins is very minor, IMHO).

Yes. And not need to maintain that web server is another big benefit.
We have considered it (the main reason: having more control over our SSL
key), but haven't decided to do that. Note that even on dedicated
server, data center staff can still access the key if they want.

Best Regards,
Marek Marczykowski-Górecki
Invisible Things Lab
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?

[marmarek]

On Sun, Oct 25, 2015 at 04:07:26PM -0700, Axon wrote:

Has it been decided to go back to self hosting? If so, is there an ETA for this? I guess it'll take time.

I didn't realize that ITL was considering going back to self-hosting (or maybe I just forgot). Any particular reason ITL wants to do that? Saving money by hosting for free on gh-pages seems like a big benefit, and it doesn't seem to be holding us back (not being able to use plugins is very minor, IMHO).

Yes. And not need to maintain that web server is another big benefit.
We have considered it (the main reason: having more control over our SSL
key), but haven't decided to do that. Note that even on dedicated
server, data center staff can still access the key if they want.

Best Regards,
Marek Marczykowski-Górecki
Invisible Things Lab
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?

[andrewdavidwong]

Auto-generating ToCs appear to be working now!

[andrewdavidwong]

Auto-generating ToCs appear to be working now!

[adrelanos]

The current TOC generator generated some confusion on my side.
(#1674 (comment))
I think the current one is not great.

• without javascript there is no table of contents
• without javascript, anchors are broken
• ugly table of contents anchors #tocAnchor-1-1-1 (example: https://www.qubes-os.org/doc/split-gpg/#tocAnchor-1-1-1)
• unstable table of contents anchors(?)
• something as simple as anchors should not depend on javascript
• nowadays noscript gets more and more popular among security consciousness users which are Qubes main audience

Are there alternatives without these shortcomings?

[adrelanos]

The current TOC generator generated some confusion on my side.
(#1674 (comment))
I think the current one is not great.

• without javascript there is no table of contents
• without javascript, anchors are broken
• ugly table of contents anchors #tocAnchor-1-1-1 (example: https://www.qubes-os.org/doc/split-gpg/#tocAnchor-1-1-1)
• unstable table of contents anchors(?)
• something as simple as anchors should not depend on javascript
• nowadays noscript gets more and more popular among security consciousness users which are Qubes main audience

Are there alternatives without these shortcomings?

[marmarek]

Are there alternatives without these shortcomings?

There is yekyll-toc-generator, but it isn't possible to use it in github pages.
Anyway, by default there are anchors set, much nicer btw (click on some subtitle and choose "inspect element", with scripts disabled). Maybe it is possible to adjust the current generator to reuse those anchors?
That would be partial solution - still no TOC without javascript, but I think that would be something.

[marmarek]

Are there alternatives without these shortcomings?

There is yekyll-toc-generator, but it isn't possible to use it in github pages.
Anyway, by default there are anchors set, much nicer btw (click on some subtitle and choose "inspect element", with scripts disabled). Maybe it is possible to adjust the current generator to reuse those anchors?
That would be partial solution - still no TOC without javascript, but I think that would be something.

[andrewdavidwong]

Maybe it is possible to adjust the current generator to reuse those anchors? That would be partial solution - still no TOC without javascript, but I think that would be something.

I sympathize with @adrelanos's concerns, and this would be a good improvement to the situation. However, it is beyond my abilities to try to do this. (I imagine that the author of tocmd-generator would have done this already if it were easy, but maybe not.)

[andrewdavidwong]

Maybe it is possible to adjust the current generator to reuse those anchors? That would be partial solution - still no TOC without javascript, but I think that would be something.

I sympathize with @adrelanos's concerns, and this would be a good improvement to the situation. However, it is beyond my abilities to try to do this. (I imagine that the author of tocmd-generator would have done this already if it were easy, but maybe not.)