-
-
Notifications
You must be signed in to change notification settings - Fork 5.6k
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
Conversation
see go-gitea#822 Signed-off-by: Michael Gnehr <michael@gnehr.de>
Codecov Report
@@ Coverage Diff @@
## master #7182 +/- ##
=========================================
Coverage ? 41.18%
=========================================
Files ? 470
Lines ? 63601
Branches ? 0
=========================================
Hits ? 26196
Misses ? 33981
Partials ? 3424
Continue to review full report at Codecov.
|
Signed-off-by: Michael Gnehr <michael@gnehr.de>
Signed-off-by: Michael Gnehr <michael@gnehr.de>
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. |
I think this should be an optional and keep false as default. |
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? |
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. |
@silverwind @silverwind @lunny @mrsdizzie
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 <michael@gnehr.de>
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 |
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. |
Signed-off-by: Michael Gnehr <michael@gnehr.de>
Signed-off-by: Michael Gnehr <michael@gnehr.de>
Thanks for the really detailed documentation in 'Hacking on Gitea'. There are some configuration options in the repository settings now.
I've updated the images above Additionally I've added some lines to support language changes in TOC headline. @mrsdizzie @lunny @silverwind @silverwind
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: Please leave a comment if i should remove this again. Edit2:
Edit2 End @silverwind -> tool for hash-based TOCs |
There was a problem hiding this 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?
+ reduce js call stack: function -> inline function Signed-off-by: Michael Gnehr <michael@gnehr.de>
it actually only add the toc if there is a rendered markdown file (and when options are enabled) Do I miss something? Or do I understand the question wrong? |
Signed-off-by: Michael Gnehr <michael@gnehr.de>
Is there a way to restart drone build without pushing a new commit? |
restarted |
For the few LESS styles you added, probably not. For external dependencies certainly. |
@Cherrg I don't think we should refactor all the scripts. Maybe keep less/css behavior the same as before. |
is wiki.js ok? As toc is also available on every markup file without wiki (if enabled in repository settings and whitelist) |
OK. Then I think |
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 |
Will this feature eventually be released? |
No. Someone should pick this up. |
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:
as a preamble. Whilst the the styling at present leaves something to be desired this has been there since 1.10... |
Also see feature request #15296. I think always rendering a auto-generated TOC outside the rendered markdown area is a reasonable request. |
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. |
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? |
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. |
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. |
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