Skip to content

Commit 307b486

Browse files
steveklabniksenekor
steveklabnik
and
senekor
committed
docs: Add doc rendering via starlight
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. Co-authored-by: Remo Senekowitsch <remo@buenzli.dev>
1 parent c49a60e commit 307b486

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

64 files changed

+7394
-188
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,3 +41,36 @@ jobs:
4141
.github/scripts/docs-build-deploy prerelease --push
4242
- name: "Show `git diff --stat`"
4343
run: git diff --stat gh-pages^ gh-pages || echo "(No diffs)"
44+
45+
starlight-docs-build-deploy:
46+
# Deploy Starlight-based docs to /starlight for comparison with MkDocs version
47+
permissions:
48+
contents: write
49+
if: github.repository_owner == 'jj-vcs' # Stops this job from running on forks
50+
runs-on: ubuntu-24.04
51+
52+
steps:
53+
- uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8
54+
with:
55+
persist-credentials: true
56+
- run: "git fetch origin gh-pages --depth=1"
57+
- name: Setup Node.js
58+
uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
59+
with:
60+
node-version: '22'
61+
- name: Install dependencies
62+
working-directory: web/docs
63+
run: npm ci
64+
- name: Build Starlight docs
65+
working-directory: web/docs
66+
run: npm run build -- --base /starlight/
67+
- name: Deploy to gh-pages/starlight
68+
run: |
69+
git config user.name 'jj-docs[bot]'
70+
git config user.email 'jj-docs[bot]@users.noreply.github.io'
71+
git checkout gh-pages
72+
rm -rf starlight
73+
mv web/docs/dist starlight
74+
git add starlight
75+
git commit -m "Deploy Starlight docs to /starlight" || echo "No changes to commit"
76+
git push origin gh-pages

‎GOVERNANCE.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Jujutsu Governance
1+
---
2+
title: Jujutsu Governance
3+
---
24

35
## Overview
46

‎docs/FAQ.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Frequently asked questions
1+
---
2+
title: Frequently asked questions
3+
---
24

35
### Why does my bookmark not move to the new commit after `jj new/commit`?
46

‎docs/bookmarks.md‎

Lines changed: 16 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
1-
# Bookmarks
2-
1+
---
2+
title: Bookmarks
3+
---
34

45
## Introduction
56

@@ -36,19 +37,19 @@ changes compared to the current record of the remote's state will be propagated
3637
to the corresponding local bookmark, which will be created if it doesn't exist
3738
already.
3839

39-
!!! note "Details: how `fetch` pulls bookmarks"
40-
41-
Let's say you run `jj git fetch --remote origin` and, during the fetch, `jj`
42-
determines that the remote's `main` bookmark has been moved so that its target is
43-
now ahead of the local record in `main@origin`.
44-
45-
`jj` will then update `main@origin` to the new target. If `main@origin` is
46-
**tracked**, `jj` will also apply the change to the local bookmark `main`. If the
47-
local target has also been moved compared to `main@origin` (probably because you
48-
ran `jj bookmark set main`), then the two updates will be merged. If one is ahead
49-
of the other, then that target will become the new target. Otherwise, the local
50-
bookmark will become conflicted (see the ["Conflicts" section](#conflicts) below
51-
for details).
40+
:::note[Details: how `fetch` pulls bookmarks]
41+
Let's say you run `jj git fetch --remote origin` and, during the fetch, `jj`
42+
determines that the remote's `main` bookmark has been moved so that its target is
43+
now ahead of the local record in `main@origin`.
44+
45+
`jj` will then update `main@origin` to the new target. If `main@origin` is
46+
**tracked**, `jj` will also apply the change to the local bookmark `main`. If the
47+
local target has also been moved compared to `main@origin` (probably because you
48+
ran `jj bookmark set main`), then the two updates will be merged. If one is ahead
49+
of the other, then that target will become the new target. Otherwise, the local
50+
bookmark will become conflicted (see the ["Conflicts" section](#conflicts) below
51+
for details).
52+
:::
5253

5354
Most commands don't show the tracked remote bookmark if it has the same target as
5455
the local bookmark. The local bookmark (without `@<remote name>`) is considered the

‎docs/changelog.md‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
1+
---
2+
title: Changelog
3+
---
4+
15
<!-- The contents of the CHANGELOG is manually kept up-to-date with PRs.
2-
--- This file only exposes it to the website.
3-
-->
6+
This file only exposes it to the website.
7+
-->
48

5-
{%
6-
include-markdown "../CHANGELOG.md"
7-
rewrite-relative-urls=true
8-
comments=true
9-
%}
9+
::include{file="../CHANGELOG.md" start="# Changelog"}

‎docs/cli-reference.md‎

Lines changed: 14 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,19 @@
1-
<!-- The contents of the CLI reference is auto-generated by a Rust test.
2-
--- If `cargo insta` is installed, you can regenerate the CLI reference with:
3-
--- cargo insta test --accept --workspace -- test_generate
4-
-->
5-
6-
!!! warning
1+
---
2+
title: CLI Reference
3+
---
74

8-
This CLI reference is experimental. It is automatically generated, but
9-
does not match the `jj help` output exactly.
5+
<!-- The contents of the CLI reference is auto-generated by a Rust test.
6+
If `cargo insta` is installed, you can regenerate the CLI reference with:
7+
cargo insta test --accept --workspace -- test_generate
8+
-->
109

11-
Run `jj help <COMMAND>` for more authoritative documentation.
10+
:::caution
11+
This CLI reference is experimental. It is automatically generated, but
12+
does not match the `jj help` output exactly.
1213

13-
If you see a significant difference, feel free to file a bug, or a PR to note the difference here.
14+
Run `jj help <COMMAND>` for more authoritative documentation.
1415

16+
If you see a significant difference, feel free to file a bug, or a PR to note the difference here.
17+
:::
1518

16-
{%
17-
include-markdown "../cli/tests/cli-reference@.md.snap"
18-
rewrite-relative-urls=false
19-
start="<!-- BEGIN MARKDOWN-->"
20-
comments=true
21-
%}
19+
::include{file="../cli/tests/cli-reference@.md.snap" start="<!-- BEGIN MARKDOWN-->"}

‎docs/code-of-conduct.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Contributor Covenant Code of Conduct
1+
---
2+
title: Contributor Covenant Code of Conduct
3+
---
24

35
## Our Pledge
46

‎docs/community_tools.md‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,14 @@
1-
# Community-built tools around Jujutsu
1+
---
2+
title: Community-built tools around Jujutsu
3+
---
24

35
Many of these tools are not complete yet, just like Jujutsu itself. But they
46
already simplify many workflows and can improve your experience.
57

6-
!!! warning
7-
The listed tools are community‑maintained; the Jujutsu project does not
8-
review, endorse, or guarantee their quality or security.
8+
:::caution
9+
The listed tools are community‑maintained; the Jujutsu project does not
10+
review, endorse, or guarantee their quality or security.
11+
:::
912

1013
## Diffedit3
1114

‎docs/config.md‎

Lines changed: 23 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Configuration
1+
---
2+
title: Configuration
3+
---
24

35
These are the config settings available to jj/Jujutsu.
46

@@ -449,11 +451,11 @@ immutable even if the set is empty.
449451
Immutable commits (other than the root commit) can be rewritten using the
450452
`--ignore-immutable` CLI flag.
451453

452-
!!! warning
453-
454-
Using `--ignore-immutable` will allow you to rewrite any commit in the
455-
history, and all descendants, without warning. Use this power wisely, and
456-
remember `jj undo`.
454+
:::caution
455+
Using `--ignore-immutable` will allow you to rewrite any commit in the
456+
history, and all descendants, without warning. Use this power wisely, and
457+
remember `jj undo`.
458+
:::
457459

458460
### Behavior of prev and next commands
459461

@@ -845,16 +847,16 @@ execute multiple jj commands with a single alias, or run arbitrary scripts that
845847
complement your version control workflow. This can be done, but be aware of the
846848
danger:
847849

848-
!!! warning
849-
850-
The following technique just provides a convenient syntax for running
851-
arbitrary code on your system. Using it irresponsibly may cause damage
852-
ranging from breaking the behavior of `jj undo` to wiping your file system.
853-
Exercise the same amount of caution while writing these aliases as you would
854-
when typing commands into the terminal!
850+
:::caution
851+
The following technique just provides a convenient syntax for running
852+
arbitrary code on your system. Using it irresponsibly may cause damage
853+
ranging from breaking the behavior of `jj undo` to wiping your file system.
854+
Exercise the same amount of caution while writing these aliases as you would
855+
when typing commands into the terminal!
855856

856-
This feature may be removed or replaced by an embedded scripting language in
857-
the future.
857+
This feature may be removed or replaced by an embedded scripting language in
858+
the future.
859+
:::
858860

859861
The command `jj util exec` will simply run any command you pass to it as an
860862
argument. Additional arguments are passed through. Here are some examples:
@@ -1431,12 +1433,12 @@ backends.ssh.revocation-list = "/path/to/revocation-list"
14311433
You can use [`jj sign`](./cli-reference.md#jj-sign)/[`jj unsign`](./cli-reference.md#jj-unsign)
14321434
to sign/unsign commits manually.
14331435

1434-
!!! warning
1435-
1436-
`jj sign` always signs commits, even if they are already signed by the
1437-
user. While this is cumbersome for users signing via hardware devices, we
1438-
cannot reliably check if a commit is already signed without creating a
1439-
signature (see [this issue](https://github.com/jj-vcs/jj/issues/5786)).
1436+
:::caution
1437+
`jj sign` always signs commits, even if they are already signed by the
1438+
user. While this is cumbersome for users signing via hardware devices, we
1439+
cannot reliably check if a commit is already signed without creating a
1440+
signature (see [this issue](https://github.com/jj-vcs/jj/issues/5786)).
1441+
:::
14401442

14411443
### Automatically signing commits
14421444

‎docs/conflicts.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
1-
# First-class conflicts
2-
1+
---
2+
title: First-class conflicts
3+
---
34

45
## Introduction
56

0 commit comments

Comments
 (0)