WIP: wiki - add toc to wiki pages and rendered md files

[Cherrg]

This will add an auto generated TOC to rendered md files and wiki pages. Only works if Javascript is enabled.

For more information see related issue.
fix #822

Wiki

Markdown

Dark Theme

Language Support

Large Screens >1760px

Repository Settings:

Signed-off-by: Michael Gnehr michael@gnehr.de

[codecov-io]

Codecov Report

❗ No coverage uploaded for pull request base (master@6fbfffe). Click here to learn what that means.
The diff coverage is 34.84%.

@@            Coverage Diff            @@
##             master    #7182   +/-   ##
=========================================
  Coverage          ?   41.18%           
=========================================
  Files             ?      470           
  Lines             ?    63601           
  Branches          ?        0           
=========================================
  Hits              ?    26196           
  Misses            ?    33981           
  Partials          ?     3424

Impacted Files	Coverage Δ
models/migrations/migrations.go	1.32% <ø> (ø)
modules/setting/setting.go	49.04% <ø> (ø)
modules/auth/repo_form.go	41.73% <ø> (ø)
models/migrations/v90.go	0% <0%> (ø)
routers/repo/setting.go	9.1% <0%> (ø)
models/repo.go	48.69% <100%> (ø)
routers/repo/view.go	45.34% <76.92%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 6fbfffe...f870a41. Read the comment docs.

[silverwind]

Going by you screenshot, I'd suggest adding either a bit more padding to the TOC box or reducing the title font size a bit. Currently it looks a bit crammed.

[lunny]

I think this should be an optional and keep false as default.

[mrsdizzie]

I don't think this is something I would want on by default and with no way to turn off.

Even in certain situations where I did want a TOC like this, I don't think I'd ever want it on all rendered markdown files. Maybe perhaps if you'd need to add something specific to the content itself to trigger the rendering, perhaps in a comment?

[silverwind]

Maybe it's best to follow GitHub here. Their Wikis have a TOC in the sidebar but READMEs haven't.

Some projects use a manually created TOC using hash link, and I think this is sufficient and works universally in every Markdown renderer which can't be said of a JS-created TOC.

[Cherrg]

@silverwind
I will update the stylesheet

@silverwind @lunny @mrsdizzie
I will try to add some configuration flags

• to enable/disable on wikipages
• to enable/disable on md files
  • only enable on md.files if %%TOC%% is written there

I've choosen JS TOC because it's fast and does not burden the server. In addition, this does not change the MD files when uploading.

[silverwind]

For the wiki, I could see a always enabled server-rendered TOC of created wiki pages, similar to how GitHub does it, beside the content, not inside the markdown content area. Then if the user enables JS TOC, extend the server-rendered TOC with sub-bullets.

For repo markdowns, I'm also not a fan of having it inside the markdown area. Some readmes include large images which would bring the risk of the TOC overlapping it. Probably best to also render it beside the readme at a fixed width, ideally not making the overall width wider than what we have on .ui.container.

[silverwind]

Just seen this tool to auto-generate hash-based TOCs. I think tools like that are the ideal solution, but I guess if you really want to continue here, I won't stop you.

[Cherrg]

Thanks for the really detailed documentation in 'Hacking on Gitea'. There are some configuration options in the repository settings now.

• enable/disable TOC on wikipages [DEFAULT: enabled]
• enable/disable TOC on all md files [DEFAULT: disabled]
• enable/disable TOC on md.files if %%TOC%% is written there [DEFAULT: enabled]

I've updated the images above

Additionally I've added some lines to support language changes in TOC headline.

@mrsdizzie @lunny
options are now available

@silverwind
reduced fontsize and added some more padding

@silverwind
currently the TOC is generated inside the rendered markdown container. Additionally the TOC is floating so there will always be some space for it (on big screens and on mobile devices). There should be no overlapping. If there are some cases please send me an example. You can try the TOC injection in every gitea instance if you

• copy the code from my comment to a webserver
  NOTE: The script in the comment has old padding and border styles and is only for default theme.
• open a console inside browser
• and run jQuery.getScript( 'https://<webserver>/path/to/toc.js' )

To place the TOC beside the markdown container there need to be some additional container next to rendered markdown in the theme to handle such content nicely on mobile devices. Currently there are none.

Edit:
May I could add some style for big screens (>1760px) so something like this could be done. (On small screens the TOC will still be inside the rendered markdown container like the images above):

Please leave a comment if i should remove this again.
Edit End

Edit2:
Played with JS code -> it could be like this if I use equal code for #823 (additional PR) and place the Containers outside of the rendered wiki page:

• same restriction screen size > 1760px

Edit2 End

@silverwind -> tool for hash-based TOCs
I did not read the comments until everything was done :)
If I'm right this script could be used with some voodo inside githooks, but this will alter the files.

[lunny]

And maybe you should check if this is a markdown file?

[Cherrg]

And maybe you should check if this is a markdown file?

it actually only add the toc if there is a rendered markdown file (and when options are enabled)
-> when markdown class is on container

Do I miss something? Or do I understand the question wrong?

[Cherrg]

Is there a way to restart drone build without pushing a new commit?

[techknowlogick]

restarted

[Cherrg]

@Cherrg I perfer to move new js code to web_src/wiki.js, otherwise LGTM.

@lunny
i will move this to web_src/toc.js (as this function could be enabled on all markup related pages (settings flag))

@silverwind

• and add some lazy-load wrapper for .js
• for css is it worth it?

[silverwind]

for css is it worth it?

For the few LESS styles you added, probably not. For external dependencies certainly.

[lunny]

@Cherrg I don't think we should refactor all the scripts. Maybe keep less/css behavior the same as before.
Named it wiki.js so that next PRs could also move other functions to it. Or we could add to a sub folder like web_src/js/wiki/toc.js.

[Cherrg]

is wiki.js ok? As toc is also available on every markup file without wiki (if enabled in repository settings and whitelist)

[lunny]

OK. Then I think toc.js is OK.

[gsantner]

Is it likely this will ever get into gitea? It's listed as dependency for wiki directory support (#7225), which is really missing.

@Cherrg As far I can see , it's mainly about resolving merge conflicts and where to put stuff right?

[silverwind]

I'd approve this if it would only add the Wiki TOC, always outside the rendered markdown area. I feel like sticking a TOC inside the markdown area is too intrusive on the content and it will also break right-aligned images in the content. Also, I think TOC should probably be rendered server-side only.

[septatrix]

I'd approve this if it would only add the Wiki TOC, always outside the rendered markdown area. I feel like sticking a TOC inside the markdown area is too intrusive on the content and it will also break right-aligned images in the content. Also, I think TOC should probably be rendered server-side only.

I fully agree. Rendering the TOC server side also should not have a heavy performance hit and goldmarks allows one to register transformation steps which can scan the ast for headers. I do not know Golang but Hugo seems to have implemented something very similar markup/goldmark/toc.go

[a96219]

Will this feature eventually be released?

[lunny]

No. Someone should pick this up.

[septatrix]

I think Github has a pretty solution for their readme files which could also be expanded to wiki pages and arbitrary markdown files if we wish. They show a TOC icon next to the filename which grants you a popover showing the headings. This is very unobtrusive and does not taint the normal layout of the markdown in any way. It does not get in the way on either small mobile devices or big screens and scales well with larger TOCs which are sometimes common in wiki pages.

See for example https://github.com/go-gitea/gitea#readme:

[zeripath]

I think Github has a pretty solution for their readme files which could also be expanded to wiki pages and arbitrary markdown files if we wish. They show a TOC icon next to the filename which grants you a popover showing the headings. This is very unobtrusive and does not taint the normal layout of the markdown in any way. It does not get in the way on either small mobile devices or big screens and scales well with larger TOCs which are sometimes common in wiki pages.

See for example https://github.com/go-gitea/gitea#readme:

https://try.gitea.io/arandomer/pathological/src/branch/master/README.md

https://try.gitea.io/arandomer/pathological/wiki/Home

Just add:

---
gitea: none
include_toc: true
---

as a preamble.

Whilst the the styling at present leaves something to be desired this has been there since 1.10...

[silverwind]

Also see feature request #15296. I think always rendering a auto-generated TOC outside the rendered markdown area is a reasonable request.

[Tony2]

Just add:

---
gitea: none
include_toc: true
---

as a preamble.

I was desperately searching for a way to enable TOC in gitea wiki. Thanks for this hint; it took me quite a lot of time before I found this.

[wxiaoguang]

This PR has been stale for very long time.

Sorry I didn't know the history of it (no idea why it's blocked), the only thing I know is:

• A backend TOC render has been merged: Automatically render wiki TOC #19873
• There are still some requirements for fine-tuning the TOC (show/hide, scroll, style, etc)

So, could this PR be closed if no more update, and do more fine-tunes in new PRs?

[silverwind]

I think we can close. The in-content TOC approach was not popular, but as we now that we have the TOC renderer, we can use it to render a button-style overlay TOC, similar to GitHub README.

[wxiaoguang]

It has been stale for a long time and I can't think of a way to handling it other than closing it. Feel free to reopen if there's any new progress and I could also help.