Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
wants to merge 25 commits into from

Conversation

Cherrg
Copy link
Contributor

@Cherrg Cherrg commented Jun 11, 2019

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

grafik

Markdown

grafik

Dark Theme

grafik

Language Support

grafik

Large Screens >1760px

grafik

Repository Settings:

grafik

Signed-off-by: Michael Gnehr [email protected]

public/js/index.js Outdated Show resolved Hide resolved
@GiteaBot GiteaBot added the lgtm/need 2 This PR needs two approvals by maintainers to be considered for merging. label Jun 11, 2019
@lafriks lafriks added type/feature Completely new functionality. Can only be merged if feature freeze is not active. and removed lgtm/need 2 This PR needs two approvals by maintainers to be considered for merging. labels Jun 11, 2019
@codecov-io
Copy link

codecov-io commented Jun 11, 2019

Codecov Report

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

Impacted file tree graph

@@            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.

@GiteaBot GiteaBot added the lgtm/need 2 This PR needs two approvals by maintainers to be considered for merging. label Jun 11, 2019
@silverwind
Copy link
Member

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
Copy link
Member

lunny commented Jun 11, 2019

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

@mrsdizzie
Copy link
Member

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
Copy link
Member

silverwind commented Jun 11, 2019

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 Cherrg changed the title add toc to wikipages and rendered md files WIP: add toc to wikipages and rendered md files Jun 12, 2019
@Cherrg
Copy link
Contributor Author

Cherrg commented Jun 12, 2019

@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.

Signed-off-by: Michael Gnehr <[email protected]>
@silverwind
Copy link
Member

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
Copy link
Member

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 Cherrg changed the title WIP: add toc to wikipages and rendered md files add toc to wikipages and rendered md files Jun 12, 2019
@Cherrg
Copy link
Contributor Author

Cherrg commented Jun 12, 2019

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):

grafik

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:

grafik

  • 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.

Copy link
Member

@lunny lunny left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

custom/conf/app.ini.sample Outdated Show resolved Hide resolved
+ reduce js call stack: function -> inline function

Signed-off-by: Michael Gnehr <[email protected]>
@Cherrg
Copy link
Contributor Author

Cherrg commented Jun 13, 2019

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
Copy link
Contributor Author

Cherrg commented Jun 13, 2019

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

@techknowlogick
Copy link
Member

restarted

@Cherrg
Copy link
Contributor Author

Cherrg commented Nov 16, 2019

@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
Copy link
Member

for css is it worth it?

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

@lunny
Copy link
Member

lunny commented Nov 16, 2019

@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
Copy link
Contributor Author

Cherrg commented Nov 16, 2019

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

@lunny
Copy link
Member

lunny commented Nov 17, 2019

OK. Then I think toc.js is OK.

@Cherrg Cherrg changed the title wiki - add toc to wiki pages and rendered md files WIP: wiki - add toc to wiki pages and rendered md files Nov 18, 2019
@techknowlogick techknowlogick modified the milestones: 1.11.0, 1.x.x Dec 12, 2019
@gsantner
Copy link

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
Copy link
Member

silverwind commented Feb 20, 2020

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
Copy link

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
Copy link

a96219 commented Jan 6, 2021

Will this feature eventually be released?

@lunny
Copy link
Member

lunny commented Jan 6, 2021

No. Someone should pick this up.

@a96219 a96219 mentioned this pull request Jan 29, 2021
12 tasks
@septatrix
Copy link

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:
image

@zeripath
Copy link
Contributor

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
Copy link
Member

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

@Tony2
Copy link

Tony2 commented Jul 16, 2021

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.

@vwbusguy vwbusguy mentioned this pull request Sep 14, 2021
@vwbusguy vwbusguy mentioned this pull request Jan 20, 2022
@lunny lunny removed this from the 1.x.x milestone Mar 20, 2023
@wxiaoguang
Copy link
Contributor

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:

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

@wxiaoguang wxiaoguang added the issue/needs-feedback For bugs, we need more details. For features, the feature must be described in more detail label Apr 25, 2023
@silverwind
Copy link
Member

silverwind commented Apr 25, 2023

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
Copy link
Contributor

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.

@wxiaoguang wxiaoguang closed this May 1, 2023
@go-gitea go-gitea locked as resolved and limited conversation to collaborators Aug 1, 2023
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
issue/confirmed Issue has been reviewed and confirmed to be present or accepted to be implemented issue/needs-feedback For bugs, we need more details. For features, the feature must be described in more detail lgtm/need 1 This PR needs approval from one additional maintainer to be merged. type/feature Completely new functionality. Can only be merged if feature freeze is not active.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

TOC for Wiki Pages