-
Notifications
You must be signed in to change notification settings - Fork 325
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
Proof of concept: Rendering docs with mdBook #4815
Conversation
LitElement, | ||
css, | ||
html, | ||
} from "https://cdn.jsdelivr.net/gh/lit/dist@3/all/lit-all.min.js"; |
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.
this is https://lit.dev, a web components framework from Google -- we can vendor it if necessary, but idk if there's a good reason for it.
React, Preact, etc would also work, but I didn't want an extra transpilation step for .jsx. With Lit, I don't need any JS tools on my machine at all.
async fetchVersions() { | ||
try { | ||
const response = await fetch( | ||
"https://martinvonz.github.io/jj/versions.json", |
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.
This file is currently generated by mike. We'd have to find another way to update it. Luckily the format is super simple:
[
{
"version": "prerelease",
"title": "prerelease",
"aliases": []
},
{
"version": "v0.23.0",
"title": "v0.23.0",
"aliases": [
"latest"
]
},
{
"version": "v0.22.0",
"title": "v0.22.0",
"aliases": []
},
{
"version": "v0.21.0",
"title": "v0.21.0",
"aliases": []
},
...
]
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.
I think we'd need a replacement for mike
, yes.
This is my main worry about this PR: for a moment, I thought that mkdocs
finally implemented a version switcher, but it seems that we'd have to take care of its guts ourselves if we go with mdbook. Perhaps they would accept such tools as part of their project?
// /(\/jj\/)[^\/]+/, | ||
/http:\/\/localhost:3000(.*)/, | ||
`https://martinvonz.github.io/jj/${selectedVersion}$1`, |
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.
Just for testing; this will be More Proper in the prod version
(I should look at mkdocs's implementation perhaps)
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.
If you go to prerelease/bookmarks/
, and switch to a pre-bookmarks jj
version, will this show an ugly 404?
A lot of the complexity in the mkdocs-material version switcher functionality comes from trying to avoid this. See e.g. squidfunk/mkdocs-material#7338 (which has tests and thus might be slightly easier to follow than what ended up merged).
It is possible that fixing it is not worth the complexity, but then we'd need to make our 404 page much nicer.
(Other than that, it's refreshing to seem how short and nice this can be)
@necauqua btw this is probably possible with mdbook (see https://docs.rs/mdbook-cmdrun/latest/mdbook_cmdrun/), but could be risky for contributors. Idk how to make it non-risky. |
Thank you for looking into this! To summarize my view on the state of mkdocs and potential improvements: mkdocs+mkdocs-material is not great; there are three serious problems with it:
I think 1 is fixable relatively easily, by switching to https://github.com/astral-sh/uv, which can install Python itself and has had all the features we need for a few months now. So, the instructions for contributors would be:
I have a draft for the uv switch, I just hadn't had a good reason to finish up. I forget what state that branch is in, but you can play with This, however, would not fix 2 or 3, which feel more serious. For those, I was considering taking a look at https://docusaurus.io, which seems to use a modern Markdown parse and has a version switcher. I've seen some new projects using it. One example: https://ki-editor.github.io/ki-editor/docs/introduction (it uses some interactive features we wouldn't need, at least at first, but it has a nice simple theme. Docusaurus docs themselves are an example with a version switcher) I am hoping that Docusaurus has some replacement for Docusaurus in the Node ecosystem, which could make 1 a problem again, but maybe we could have it run in Deno or Bun. Those are as easy to install as Update: Or maybe there is some Update 2: On Discord, @chriskrycho mentioned the Vue.js docs as a nice example. They seem to use https://github.com/vuejs/vitepress , which looks very similar to Docusaurus from a distance, but might have other pros/cons. On second look, they don't seem to support versioning though. Aside on versioning: wanting a publishing system with versioning restricts us a lot. If this is really a problem, we could switch to just having two docs websites: on for prerelease version and one for latest stable version. Still, I'd try Docusaurus first. Also, that'd break a lot of our URLs. I have not myself seriously considered adding a version switcher to MkBook, that (together with making a replacement for |
In Node, as long as you have Node on your system, you can use |
Yes, I wonder if they have a solution to it. Now that Actually, node can be installed by |
Docusaurus does versioning by copying past versions into the repo, see
I feel like it's the version switcher specifically that limits us -- otherwise you're free to pick any static site generator and serve the list of folders. It covers the usecase of "I'm stuck on an old version and I need docs for that" (Docusaurus does this with older 2.x versions). I suppose we'd also need a bit of logic to inject "this version is old" banners into past docs. |
I just remembered that Proto exists: https://moonrepo.dev/docs/proto |
Yeah, Proto turns out to be neat.
|
Just checking that mdbook works.
Includes a version selector.
How to run:
brew install mdbook # or: cargo install mdbook (untested) mdbook serve
Most of the theme/ files can be removed, except for
index.hbs
. We might want to make this a plugin or smth so that we don't have to track templates from the official mdbook. Or we can inject the element dynamically and then we don't need to vendor any theme files at all, just set upoutput.html.additional-js = ...
.a few tasks