Table of Contents in pages #87

New Issue

pat-s · 2020-12-03T08:02:05Z

pat-s commented

2020-12-03 08:02:05 +00:00

Would make pages more readable imo. Happy to issue a PR.

All it needs is the following in layouts/doc/single.html

{{ if and (gt .WordCount 400 ) (.Params.toc) }}
<aside>
  <header>
	<h2>{{.Title}}</h2>
  </header>
  {{.TableOfContents}}
</aside>

(the wordcount condition is optional but I think it makes sense)

Would make pages more readable imo. Happy to issue a PR. [![Screen-Shot-2020-12-03-at-8-36-15-AM.png](https://i.postimg.cc/6QfwrhwH/Screen-Shot-2020-12-03-at-8-36-15-AM.png)](https://postimg.cc/Z9n1ZpW3) All it needs is the following in `layouts/doc/single.html` ```html {{ if and (gt .WordCount 400 ) (.Params.toc) }} <aside> <header> <h2>{{.Title}}</h2> </header> {{.TableOfContents}} </aside> ``` (the wordcount condition is optional but I think it makes sense)

image.png

198 KiB

lunny added the

kind/proposal

label 2020-12-03 10:24:20 +00:00

jolheiser commented

2020-12-03 21:47:53 +00:00

This looks great! I'm not entirely familiar with all the things Hugo allows, but is it possible to selectively disable this?

The theme is used for more then the docs (blog being my main concern for hitting the word count), and we may not always want a TOC.

Alternatively, selectively enabling might be better. Most, if not all, docs pages would probably benefit from a TOC.

This looks great! I'm not entirely familiar with all the things Hugo allows, but is it possible to selectively disable this? The theme is used for more then the docs (blog being my main concern for hitting the word count), and we may not always want a TOC. Alternatively, selectively _enabling_ might be better. Most, if not all, docs pages would probably benefit from a TOC.

techknowlogick commented

2020-12-03 22:12:25 +00:00

I think hugo supports settings "per post"(or content page), and we could have toc: true on the longer pages?

I think hugo supports settings "per post"(or content page), and we could have `toc: true` on the longer pages?

6543 commented

2020-12-04 00:51:26 +00:00

so pulls like https://github.com/go-gitea/gitea/pull/13836 would not be needed ?

6543 commented

2020-12-04 01:09:19 +00:00

I like the look of 13836 (Page Title - description/summary - TOC - Content)

jolheiser commented

2020-12-04 03:58:12 +00:00

The benefit here is it's automatically generated so we don't need to manually keep it up to date.

pat-s commented

2020-12-04 05:44:43 +00:00

I think hugo supports settings "per post"(or content page), and we could have toc: true on the longer pages?

Yes, toc: true/false should be respected.

The condition on the word count set in my example (400) is optional - but I like it because it does not force add a ToC if the post is too short and contains only 1 or 2 headings.
You can test this locally with the gitea docs and see which pages are omitted.

so pulls like https://github.com/go-gitea/gitea/pull/13836 would not be needed ?

Correct. And I would try to avoid including semi-automatic approaches tied to an editor plugin (even though I use such for myself). Hugo can do this.
I also think the style could be adjusted somewhere.

> I think hugo supports settings "per post"(or content page), and we could have toc: true on the longer pages? Yes, `toc: true/false` should be respected. The condition on the word count set in my example (400) is optional - but I like it because it does not force add a ToC if the post is too short and contains only 1 or 2 headings. You can test this locally with the gitea docs and see which pages are omitted. > so pulls like https://github.com/go-gitea/gitea/pull/13836 would not be needed ? Correct. And I would try to avoid including semi-automatic approaches tied to an editor plugin (even though I use such for myself). Hugo can do this. I also think the style could be adjusted somewhere.

6543 commented

2020-12-04 15:51:08 +00:00

@pat-s would you mind to file a pull?

lafriks referenced a pull request that will close this issue

2020-12-04 16:11:31 +00:00

Add TOC section in documentaion pages #89

pat-s commented

2020-12-06 07:37:55 +00:00

@6543 I see you went ahead already :) Do you continue there with CSS tweaks etc. or are you waiting for me?

6543 commented

2020-12-06 07:41:45 +00:00

@lafriks created a pul I just tested things

pat-s commented

2020-12-06 13:13:47 +00:00

To move the ToC below h1 we need to define a shortcode in layouts/shortcode and use it at the appropriate place in each post, e.g.

# Installation with Docker

{{< toc >}}

See also this post.
This gives the ability to position the ToC anywhere and also modifiy it via it's own CSS class.

In addition in each post toc: false needs to be set to suppress the top-level ToC creation.
Also ToC levels are only rendered starting from h2, so all posts would need to follow this rule.

There are two possible locations for the new toc.html file:

docs/layouts/shortcodes/toc.html (contains aldready 4 other shortcodes)
docs/themes/gitea/layouts/shortcodes/toc.html (currently empty)

I'd say it can be defined directly in the theme?

toc.html:

<div class="toc">
  {{ .Page.TableOfContents }}
</div>
<br>

This then renders as follows

To move the ToC below `h1` we need to define a shortcode in `layouts/shortcode` and use it at the appropriate place in each post, e.g. ```md # Installation with Docker {{< toc >}} ``` See also [this post](https://ruddra.com/hugo-add-toc-anywhere/). This gives the ability to position the ToC anywhere and also modifiy it via it's own CSS class. In addition in each post `toc: false` needs to be set to suppress the top-level ToC creation. Also ToC levels are only rendered starting from `h2`, so all posts would need to follow this rule. There are two possible locations for the new `toc.html` file: - `docs/layouts/shortcodes/toc.html` (contains aldready 4 other shortcodes) - `docs/themes/gitea/layouts/shortcodes/toc.html` (currently empty) I'd say it can be defined directly in the theme? `toc.html`: ```html <div class="toc"> {{ .Page.TableOfContents }} </div> <br> ``` This then renders as follows ![image](/attachments/ecf5aa7b-a219-45d4-8a64-3ed9a8a26ec7)

image.png

88 KiB

👍 1

pat-s referenced this issue

2020-12-06 13:14:43 +00:00

Add TOC section in documentaion pages #89

pat-s commented

2020-12-06 13:37:51 +00:00

@techknowlogick I got a PR ready but cannot fork because "You cannot fork a repo you own". However I also do not have push rights to this repo.

Could you have a look?

@techknowlogick I got a PR ready but cannot fork because "You cannot fork a repo you own". However I also do not have push rights to this repo. Could you have a look?

6543 commented

2020-12-06 14:40:01 +00:00

so in this case we do not have to alter the theme, we just have to update the docs ... I'll file a pull

pat-s commented

2020-12-06 15:07:26 +00:00

so in this case we do not have to alter the theme, we just have to update the docs ... I'll file a pull

I'd say we should alter the theme as described above. And then file a pull with the required changes in gitea/docs.

But it would be great if new contribs could at least fork this repo here :)

> so in this case we do not have to alter the theme, we just have to update the docs ... I'll file a pull I'd say we should alter the theme as described above. And then file a pull with the required changes in `gitea/docs`. But it would be great if new contribs could at least fork this repo here :)

jolheiser commented

2020-12-06 21:36:19 +00:00

That's a bad error message (and probably just a side-effect of a template PR)

@pat-s You already have a fork, so that's why you got the You cannot fork a repo you own error. ?

That's a bad error message (and probably just a side-effect of a template PR) @pat-s You already have a [fork](https://gitea.com/pat-s/theme), so that's why you got the `You cannot fork a repo you own` error. ?

pat-s commented

2020-12-07 06:43:05 +00:00