Skip to content
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

Closed
wants to merge 3 commits into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
/target/
/rendered-docs
/book
.direnv
.envrc
# Generated by nix build, nix-build
Expand Down
6 changes: 6 additions & 0 deletions book.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
[book]
authors = ["Jujutsu contributors"]
language = "en"
multilingual = false
src = "docs"
title = "Jujutsu"
8 changes: 8 additions & 0 deletions docs/SUMMARY.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
# Summary

[Introduction](index.md)

# Reference

- [Revsets](revsets.md)
- [Templates](templates.md)
69 changes: 69 additions & 0 deletions docs/versionSelector.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
import {
LitElement,
css,
html,
} from "https://cdn.jsdelivr.net/gh/lit/dist@3/all/lit-all.min.js";
Copy link
Contributor Author

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.


class VersionSelector extends LitElement {
static styles = css`
select {
padding: 5px;
margin: 10px 0;
font-size: 100%;
}
`;

static properties = {
versions: { type: Array },
};

constructor() {
super();
this.versions = [];
}

connectedCallback() {
super.connectedCallback();
this.fetchVersions();
}

async fetchVersions() {
try {
const response = await fetch(
"https://martinvonz.github.io/jj/versions.json",
Copy link
Contributor Author

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": []
  },
  ...
]

Copy link
Contributor

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?

);
if (response.ok) {
this.versions = await response.json();
}
} catch (error) {
console.error("Error fetching versions:", error);
}
}

handleVersionChange(e) {
const selectedVersion = e.target.value;
const currentUrl = new URL(window.location);
const newUrl = currentUrl.href
.replace(
// /(\/jj\/)[^\/]+/,
/http:\/\/localhost:3000(.*)/,
`https://martinvonz.github.io/jj/${selectedVersion}$1`,
Comment on lines +48 to +50
Copy link
Contributor Author

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)

Copy link
Contributor

@ilyagr ilyagr Nov 9, 2024

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)

)
.replace(/\.html$/, "");
window.location.href = newUrl;
}

render() {
// TODO: show .aliases as well
return html`
<select @change="${this.handleVersionChange}">
${this.versions.map(
(version) =>
html`<option value="${version.version}">${version.title}</option>`,
)}
</select>
`;
}
}

customElements.define("version-selector", VersionSelector);
Loading
Loading