feat: automatic sidebar

[Hunam6]

I was wondering, why do we need to manually set a sidebar in the config? Couldn't this be generated automatically according to the folder/file hierarchy?

With this hierarchy

docs
├── index.mdx
├── page-at-root.mdx
├── part-one
│   ├── abc.mdx
│   └── index.mdx
└── part-two
    └── foo.mdx

Those pages would be the accessible: /, /page-at-root, /part-one, /part-one/abc, /part-two/foo.

And the title of the pages would be customisable using the title frontmatter.

[cabljac]

yeah thought about this myself actually. It might be a nice default setting to have, though it would require at least one extra request to github (they do a recursive REST endpoint) which shouldn't be too much of an issue.

@Salakar @Ehesp any opinions on this?

[cabljac]

So the issue is we can't get the frontmatter without querying each file individually. Without querying each file, we wouldn't be able to display their title, or order, or whether or not they're hidden/redirect pages.

[Hunam6]

I didn't thought of that, but I don't think this is an issue. I just checked and Docusaurus is doing the exact same thing (except that they use # title instead of frontmatter).

[Ehesp]

Docusaurus sources from local files on your file system, docs.page integrates directly with the GitHub API (hence why it's zero config)

[Hunam6]

I see your point but I still don't think that this is an issue. Furthermore, this should be done because right now it isn't really "zero config", except if you don't want to use the sidebar at all and you want your users to navigate with links on the pages. This addition would make docs.page truly zero config.

[cabljac]

So an alternative solution would be to include a command in our CLI to generate the sidebar

[Hunam6]

With this workaround you get away from zero config because you can no longer setup your docs by only using this

[Hunam6]

That said, tell me if I'm wrong but you can get the whole automatic sidebar working using only two requests right? One on the REST endpoint to get the list of all files and the other on the GRAPHQL endpoint to get the content of all the files listed on the first one.

[cabljac]

I'm not sure if that's possible with the GraphQL if you've got nested directories? it might require a recursive call through each layer.

If it was though, we would have to handle a few issues:

• we would have to disallow nested directories as we no longer support deep nested sidebar links
• getting all the content of all the files might be a huge request? Not sure what the implications of doing this for each time we populate the sidebar are.
• not so much an issue but then a side dependency would be supporting things like ordering the files from the frontmatter

[Hunam6]

I'm not sure if that's possible with the GraphQL if you've got nested directories? it might require a recursive call through each layer.

Yes you're right.

We could also use GraphQL (or REST) to download the ZIP file and from it we could efficiently get the tree structure, the content of the files etc.

query { 
  repository(owner: $owner, name: $repo) {
    ref(qualifiedName: $ref) {
      target {
        ... on Commit{
          zipballUrl
        }
      }
    }
  }
}

[Hunam6]

What are your thoughts about this?

[Ehesp]

Hello

This unfortunately won't be possible - downloading the archive of a repo just to achieve this will be too intensive and slow, since pages are generated on-demand.