Dvc.org: update or remove sidebar.json

[iAdramelk]

Before we migrate to gatsby we were required to store pages metadata separately from the md pages themselves in sidebar.json file.

After migration we are not really require it. We can move all relevant page data to the file's frontmatter section and build paths based on the folder structure.

It will allow us to simplify build and remove hacks like that: https://github.com/iterative/dvc.org/blob/5f589deee8fa32aca0f8c498947649fa02a87099/src/components/Documentation/SidebarMenu/index.js#L31

[pavelgrinchenko]

But we can't remove sidebar.json completely. It regulates structure for documents.
Of course we can adjust order by some prefixes in documents, like 01-document-name, but if we want add new page between others it will lead us to the hell.
@iAdramelk wdyt?

[iAdramelk]

@pavelgrinchenko yes, the idea was to sort them by prefix, but with some place to inserting pages: 10, 20, 30, etc. Instead of 1, 2, 3. See our internal handbook. The largest sections (like command reference) are sorted by command name anyway. The question is how often will other sections change.

[jorgeorpinel]

Hi! I kind of like the numeric prefixing standard for everything in the contents dir, even subdirs. But the 2 digit solution to avoiding Git conflicts doesn't convince me much. Is it really that bad that we have to change the prefix of existing file to insert stuff in between? From my PoV (writing a bunch of docs) it doesn't sound like an issue. Git typically knows when files have been moved during merges. And we don't change the structure thaaat often.

[shcheklein]

My 2cs - I'm fine with sidebar to be honest. There are two things I don't like so far:

1. redirects (we had to put some of those into redirects.json to support index-less pages in sidebar) - not a good idea, we agreed with @pavelgrinchenko that he will make this fallback logic part of the redirects middleware for now.

2. hot reload does not work properly when we do some changes to the sidebar. Can we make it work w/o removing sidebar and renaming all the files? cc @iAdramelk Ideally, in dev mode we should be able to pick up any changes.

[jorgeorpinel]

Yeah, if we can make hot reload recon sidebar.json changes then let's keep it. And in that case/ on that note, can we look into separating sidebar.js into 2 (one for load time, one for run time) and rewrite it with loops instead of recursive functions (for clarity and performance)? See #894 for more details.

[shcheklein]

loops instead of recursive functions (for clarity and performance)

this one is arguable. I personally would prefer recursion if it improves readability and needs less code.

separating sidebar.js into 2 (one for load time, one for run time)

I don't think we use any logic from it in run-time now cc @iAdramelk @pavelgrinchenko ?

[jorgeorpinel]

The current structure of sidebar.js has too many functions that are only used in one other fn first of all, from what I remember. So we could improve readability by refactoring those. And also rewriting the recursive ones I think could make the code more obvious and readable, but I'd have to try to make sure.

[iAdramelk]

We can at least move titles, help links and other meta to the fronmatter. They there in sidebar only because otherwise with nextjs we would have to load all md files to build menu.

[shcheklein]

@iAdramelk

help links

you mean interactive tutorials?

meta

I think we need to extract it automatically for docs

[iAdramelk]

@shcheklein

you mean interactive tutorials?

Yep

I think we need to extract it automatically for docs

Then we can do it automatically - yes. Then we have title which is different from the filename - we should write title in the file's frontmatter, and not to the separate config file.

[jorgeorpinel]

Hi. You mean add frontmatter to all .md docs? Can that be avoided or just use the H1 as title regardless of the file name or label in sidebar.json?

[iAdramelk]

@jorgeorpinel I mean that right now sidebar.json works like that:

By default we get the .md filename and transform it to the three things: filename, slug and menu item title. It works, except from the situation then we want to use different text in menu item title,. use ' in the name, etc. In this case we need to write title separately. Same with the slug.

What I want to say is that slug and maybe menu title should be not a part of sidebar.json, but a part of file frontmatter instead. We still can automatically generate it from the filename by default, but if we want to change it, I think correct place should be in the .md file itself, and not it the menu config.

[jorgeorpinel]

An optional frontmatter wouldn't hurt for sure, as long as it falls back to the current behavior I think

[jorgeorpinel]

@rogermparent hi! What do you think about this issue? Seems to me we have a pretty well working engine now so if it's not broken, why fix it? (i.e. should we close this one?)

[rogermparent]

That sounds fine to me, @jorgeorpinel! Any issues and/or improvements that come up with the current sidebar can be brought up in new, more specific issues in the future.

[jorgeorpinel]

@shcheklein please reopen if I got this wrong.