Feat: ability to generate docs from repo URL

[jorroll]

So nextra looks pretty easy to use already, but even easier then asking users to deploy their own app would be if they could just point https://nextra.vercel.app/ at a repo and have the docs automatically generated!

For example, lets take a repo I maintain, https://gitlab.com/john.carroll.p/rschedule. It would be nice if navigating to this URL automatically generated a docs site for rSchedule without any further effort on my part. No deploying an app, no configuration, nothing but type a url into the browser.

For example:

https://nextra.vercel.app/d/gitlab/john.carroll.p/rschedule/branch/master/docs/1.%20Introduction.md

or

https://nextra.vercel.app/d/gitlab/john.carroll.p/rschedule/tag/v1.2.5/docs/2.%20Usage/1.%20Overview.md

The API for this would be in the form

https://nextra.vercel.app/d/[repo-provider]/[project-namespace]/[project-name]/[ref-type]/[ref]/[...filePath]

When a user entered a URL like this, Nextra would use the public Gitlab / Github API to grab the repo metadata, grab the relevant markdown file, render the markdown file as a nextjs site, and cache the results. By convention, we could say that the "docs folder" would always be located at the top level of the repo in a folder named docs. Nextra could then recursively fetch all the files in the repo's docs folder (again using the public github / gitlab APIs) and build a filetree which would be used for navigating.

This would provide open source devs with the easiest method I can imagine for generating nice documentation. If people wanted more customization, they could always deploy their own Nextra site like they can currently. But I maintain a number of repos and I really don't want to do anything to generate documentation.

Coincidently, I actually spent the last two weeks building an open source project that does exactly this (also using nextjs)! You can see the (WIP) repo here:

• https://gitlab.com/john.carroll.p/dynodocs

You can see it dynamically generate documentation here. To reiterate, the documentation at this link is generated dynamically based on the provided URL.

• https://dynodocs.dev/d/gitlab/john.carroll.p/rschedule/branch/v1/docs/1.%20Introduction.md

The source for that link is this file:

• https://gitlab.com/john.carroll.p/rschedule/-/blob/v1/docs/1.%20Introduction.md
  • Notice how this markdown file contains relative links inside it. E.g. the link for the Usage Overview header is [Usage Overview](./2.%20Usage/1.%20Overview.md). These relative links are compiled to the appropriate absolute URLs by the dynodocs.dev site. This is nice because people browsing the markdown in the repo itself (instead of via dynodocs.dev) can still use the links to navigate.

This repo is very much a work in progress though, and I didn't realize that Nextra existed until this very moment. Nextra looks much further along and I like it so far! If you're amendable to this idea, I'd prefer to stop working on my repo and start contributing this functionality to yours.

What do you think? Thanks!

PS: by necessity, generating docs by a URL with so little configuration will have drawbacks. I'm not saying this option should be instead of the current Nextra functionality, but in addition to the current functionality.

[jorroll]

It also seems possible that the functionality I describe would be better as a fork of this repo. But figured I'd reach out and see what you thought first.

[jorroll]

I just realized that Nextra is not open source... This repo only appears to contain the docs 🤦

[shuding]

@thefliik Nextra is open sourced, check the core branch.

[jorroll]

Well awesome! I'm not sure if I've ever encountered a repo separated like this before. Is it temporary?

Any thoughts about my original idea?

Edit: Now I see the comment in the README instructing contributors to look at the core branch.