Add doc rendering via starlight

[steveklabnik]

This change adds a new docs deployment to /starlight/, and that's rendering the documentation via Starlight: https://starlight.astro.build/

mkdocs is no longer being maintained, and we'd like to move away from it for that reason. We've chosen starlight for two main reasons: first, it has a goal of minimizing JavaScript on the front end, and that aligns with our priorities. Second, it is based on Astro.js, which would also be a good tool for writing a basic marketing site. The overall sentiment from community in the Discord was leaning towards Astro when we were talking about this.

After a few days of checking out the new docs and making sure that things are good, we can move to making this the default.

Part of #7959.

---

This PR is not actually ready to merge as-is. The reason is this: I wanted to demonstrate the actual diff of this PR, and so I modified the files in docs. However, that means they aren't going to properly render with mkdocs. However, this is actually easy to fix: there's this line in the config:

const docsDir = fileURLToPath(new URL('../../docs', import.meta.url));

This let us use the existing docs dir. I can easily instead copy the files to web/docs/src/docs, and modify them there, and then we'll have both copies while we try it out. I'm not sold on if we should keep the configuration to use docs at the top level permanently or move the files into the actual site in the long run, but before this gets merged, we should do the duplication just to try it out. If anything modifies those files before we make this permanent, I'll make sure to reconcile things.

[github-actions]

The following commits do not follow our format for subject lines:

• 0f27121: Add doc rendering via starlight

Commits should have a subject line following the format <topic>: <description>. Please review the commit guidelines for more information.

[steveklabnik]

fun story: this line cost me ~2 hours of debugging: the markdown implementations differ ever so slightly, and without this blank line, it doesn't recognize git-autocrlf as a link target.

All commits are now correctly formatted. Thank you for your contribution!

[steveklabnik]

Oh also, I based this off of @senekor 's work over at main...senekor/starlight-docs, so would love a review from him especially.

[martinvonz]

Is this a markdown table? It looks like we're sacrificing readability in the GitHub-rendered form for better rendering with starlight. I suppose there should be little reason to look at GitHub's rendering, especially if we can get renderings from PRs with starlight, so we can review the rendered output. Oh, perhaps these new titles will not be rendered as a heading at the top of the page so this is more like a directive to starlight?

[PhilipMetzger]

I think preserving the title in GH's rendering is worth it, since it simplifies contributions.

Oh, perhaps these new titles will not be rendered as a heading at the top of the page so this is more like a directive to starlight?

Yes, that's the main reason.

[senekor]

The title in the frontmatter is required:
https://starlight.astro.build/reference/frontmatter/#title-required

I don't think this is a big deal wrt. contributions. Small edits via the GitHub UI usually don't add or completely overhaul a docs page where the title would be touched. At the end of the day, there are a lot of things that look different in the rendered web page compared to GitHub's markdown preview.

[steveklabnik]

It is YAML frontmatter, yes. This is super common for these sorts of tools.

It renders on GitHub like this: https://github.com/steveklabnik/jj/blob/307b486f758800c9b286152a2f9189acdbc5fbe1/docs/design/git-submodule-storage.md

Oh, perhaps these new titles will not be rendered as a heading at the top of the page so this is more like a directive to starlight?

It's a directive to Starlight but Starlight uses that directive to render the h1 with the title.

[senekor]

This looks great!

I noticed a couple ??? blocks in revsets.md, which previously rendered as an exapandable box. Now its content is rendered normally, which should probably be fixed.

Starlight's "aside" don't seem to have a "collapsible" feature:
https://starlight.astro.build/guides/authoring-content/#asides

It seems that it is preferred to use a regular <details> element:
https://starlight.astro.build/guides/authoring-content/#details

However, the way these details are rendered, they draw much less attention to themselves as the expandable boxes of the current docs.

It is possible to nest <details> inside an aside, but that looks a little weird. Maybe we can use some light custom CSS to make the regular <details> stand out more?

screenshots

current version:

regular <details>:

<details> inside an aside:

Here's a patch replacing the blocks with <details>. It can be applied quickly with:

curl https://github.com/jj-vcs/jj/commit/9a6826d79d907593cc9f2e0c6f55906102294c4d.patch | git apply

[steveklabnik]

@senekor I agree that it's non-obvious, yeah. Here's something I cooked up quickly, both closed and open, with the blue on hover:

I am frankly pretty bad at CSS so I'm open to literally anything here.

[steveklabnik]

I think the CLA bot is maybe upset by the co-authored by?

[PhilipMetzger]

I think the CLA bot is maybe upset by the co-authored by?

Remo's public email is not the one which is associated with his CLA which gaetan found out. I presume its fine to drop it.

[steveklabnik]

Ah I see. Well @senekor had told me before it's okay if I didn't include him, but I wanted to make sure he got credit, so I've dropped it for now, @senekor if you change your mind let me know what to add back :)

[senekor]

Here's something I cooked up quickly, both closed and open, with the blue on hover

I think it looks fantastic, in both dark and light mode.

Yeah, I'm still fine with dropping the co-authored tag.

I'm not thrilled in general about the CLA incentivizing us to doctor our authorship information. But that's a separate topic.

[steveklabnik]

Okay, so, the only thing I'd have to do before this is ready is "move the modified docs into starlight and restore the top-level docs for mkdocs." Should I do that, or is there more stuff I should change?