Add a table of contents and fix disappearing underscores in subsections #2414
Conversation
There was a problem hiding this comment.
Hey, thank you for taking the time to propose this TOC.
Looking at the rendered result I'm not sure how big of an improvement this is.
There is a long list of items and I feel when you are looking for something specific you would ctrl + f your way to it because of the number of items in the list.
Perhaps it is better to make the search box work when you enter a setting name to get to the right location.
| More info: https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one#table-of-contents | ||
| --> | ||
| ## Index<!-- omit in toc --> | ||
| - [Configuration](#configuration) |
There was a problem hiding this comment.
This anchor is wrong, should be #Configuration.
There was a problem hiding this comment.
Actually, it's #configuration, see https://github.com/fsprojects/fantomas/blob/b11b645a997a0baa2dea51a7c1aba570ce9dceca/docs/docs/Configuration.md#configuration
There was a problem hiding this comment.
I really want you to start using fsdocs here 😔.
That is the thing we use to generate the output:
https://github.com/fsprojects/fantomas/blob/master/docs/.README.md
There was a problem hiding this comment.
I’d want to, I just didn’t know how (at least not trivially). Looks like fsdocs does not read the added anchors. They were there to prevent ambiguity in the auto creation of header anchors, which apparently each markdown reader does differently.
So, the code explicitly has the lowercase c here, fsdocs just totally ignores it…
| --> | ||
| ## Index<!-- omit in toc --> | ||
| - [Configuration](#configuration) | ||
| - [Default `.editorconfig` settings](#default-editorconfig-settings) |
There was a problem hiding this comment.
It should be #Default-settings please verify all these links locally.
There was a problem hiding this comment.
Actually, it's #default-editorconfig-settings, I did verify, see: https://github.com/fsprojects/fantomas/blob/b11b645a997a0baa2dea51a7c1aba570ce9dceca/docs/docs/Configuration.md#default-editorconfig-settings
| @@ -53,9 +104,12 @@ fsharp_strict_mode=false | |||
| Please note that you should only add settings to the `.editorconfig` file when you want to deviate from the default settings. | |||
| Copying the entire list above is unnecessary. | |||
|
|
|||
| ### indent_size | |||
| # Each setting explained | |||
There was a problem hiding this comment.
I'm not really a fan of having multiple h1 headers on the same page.
We don't do this on the other pages, the h1 should be the title of the page and only occur once.
Please address.
There was a problem hiding this comment.
@nojaf, yes, that was my main point here. I didn't really like that either, but it originally rendered better with the ToC. I can remove Configuration from the ToC, but as you mentioned above, maybe there won't be a ToC at all. So either way, I'll resolve.
| # Each setting explained | ||
|
|
||
| <a id="indent_size"></a> | ||
| ## indent\_size |
There was a problem hiding this comment.
I'm on the fence about this one. Escaping work and appears to be legal Markdown, however, it is a missed opportunity to tackle fsprojects/FSharp.Formatting#389.
There was a problem hiding this comment.
@nojaf I had a quick look at that and that should be solved, sure, but I lack the time and don't know enough (yet) of that lib. Also, if I'm not going to fix it, the bug has been out there for 6 years... hence this approach for the time being.
| <!-- | ||
| This index can be auto-generated with VS Code's Markdown All in One extension. | ||
| The ToC will be updated-on-save, or can be generated on command by using | ||
| Ctrl-Shift-P: "Create table of contents". |
There was a problem hiding this comment.
Not really a fan of using a format because of the convenience of a certain plugin in a certain editor. My editor (Rider) does something different, so this is a bit unfortunate there is no real standard.
There was a problem hiding this comment.
@nojaf I agree. But yeah, there's no standard. And of course, other plugins can be used. I'll remove the comment.
Is there a trivial way to see the rendered result from the repo? I just checked "View file", which showed the links working, but I have the feeling that
@nojaf That could work. Or a collapsible ToC. Not sure there's any (standard?) way of doing either, though, as it should be on the page. I do have to say, while working on it, it was nice to be able to click back and forth between the items. The page is rather long, and the ToC is a little bit more readable as a list of available options than the |
|
Perhaps I'm missing something, but won't fsprojects/FSharp.Formatting#760 render this PR at least partially redundant? |
|
Yes, and this PR was the trigger, apparently, for @nojaf to fix it. Which is great! |
|
@nojaf, thanks for that fix, and glad it got merged so quickly! I guess I can undo most changes (glad so, it’s better with proper support!). Would still like to have the ToC in, but if you think it’s to intrusive, we can probably close this with no action. |
|
Hello @abelbraaksma, following up on this, we would go for a slightly different approach in #2427. |
|
@nojaf no worries, glad I triggered the discussion:) |
Fixes: #2411
As in the title. This adds a ToC to the
Configuration.md, which is the core reference of all things configuration. I struggled a little with what level the subsections should be at, I ended up making the 2nd level, as opposed to the original 3rd level, as that aligned better with the ToC. Hope that's ok.This also fixes the issue with underscores in titles being rendered improperly (actually: I hope it fixes them, I replaces the underscores with an escaped underscore, which is still legal MD, but hope that
FSharp.Formattingcorrectly knows what to do with it). See also: fsprojects/FSharp.Formatting#389.Note that, because of the way that MD auto-creates anchors of subsections and these anchors contain illegal characters for IDs, I had to add the anchors manually. I did this automated, but for new sections being added, this pattern should be repeated and the ToC should be re-updated.