Render ANSI sequences without transforming to HTML

dhruvkb · dhruvkb · commit 4da175284615 · 2025-04-15T19:28:29.000+04:00
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -144,7 +144,7 @@ jobs:
         with:
           cache: pnpm
           node-version-file: .nvmrc
-          cache-dependency-path: docs/pnpm-lock.yaml
+          cache-dependency-path: "**/pnpm-lock.yaml"
         env:
           COREPACK_INTEGRITY_KEYS: '{"npm":[{"expires":"2025-01-29T00:00:00.000Z","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","keytype":"ecdsa-sha2-nistp256","scheme":"ecdsa-sha2-nistp256","key":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE1Olb3zMAFFxXKHiIkQO5cJ3Yhl5i6UPp+IhuteBJbuHcA5UogKo0EWtlWwW6KSaKoTNEYL7JlCQiVnkhBktUgg=="},{"expires":null,"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","keytype":"ecdsa-sha2-nistp256","scheme":"ecdsa-sha2-nistp256","key":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEY6Ya7W++7aUPzvMTrezH6Ycx3c+HOKYCcNGybJZSCJq/fd7Qa8uuAKtdIkUQtQiEKERhAmE5lMMJhP8OkDOa2g=="}]}'
 
diff --git a/docs/astro.config.ts b/docs/astro.config.ts
@@ -21,9 +21,13 @@ export default defineConfig({
       expressiveCode: {
         themes: ["catppuccin-mocha", "catppuccin-latte"],
       },
-      social: {
-        github: "https://github.com/pls-rs/pls",
-      },
+      social: [
+        {
+          icon: "github",
+          label: "GitHub",
+          href: "https://github.com/pls-rs/pls",
+        },
+      ],
       sidebar: [
         {
           label: "About",
@@ -124,7 +128,4 @@ export default defineConfig({
       ],
     }),
   ],
-  markdown: {
-    smartypants: false, // SmartyPants converts '--' into en-dash, breaking alignment.
-  },
 });
diff --git a/docs/package.json b/docs/package.json
@@ -11,9 +11,9 @@
     "fmt": "prettier --ignore-path .gitignore --ignore-path .prettierignore --write ."
   },
   "dependencies": {
-    "@astrojs/starlight": "^0.30.6",
-    "astro": "^5.1.5",
-    "astro-auto-import": "^0.4.2"
+    "@astrojs/starlight": "^0.33.2",
+    "astro": "^5.6.2",
+    "astro-auto-import": "^0.4.4"
   },
   "packageManager": "pnpm@9.15.5"
 }
diff --git a/docs/pnpm-lock.yaml b/docs/pnpm-lock.yaml
diff --git a/docs/src/styles/terminal.css b/docs/src/styles/terminal.css
@@ -47,7 +47,9 @@ pre.terminal p {
   overflow-x: auto;
 }
 
-div.expressive-code + pre.terminal {
+/* Join output code block into its preceding command block */
+div.expressive-code:has(figure.is-terminal)
+  + div.expressive-code:not(:has(figure.is-terminal)) {
   margin-top: 0;
-  border-width: 1px 0 0 0;
+  border-top: 1px solid var(--sl-color-gray-4);
 }
diff --git a/docs/src/styles/typography.css b/docs/src/styles/typography.css
@@ -3,7 +3,7 @@ span.math {
   font-style: italic;
 }
 
-figcaption.header:has(span.sr-only) ~ pre .ec-line .code::before {
+pre[data-language="bash"] .ec-line .code::before {
   content: "$ ";
   opacity: 0.5;
 }
diff --git a/examples/justfile b/examples/justfile
@@ -12,7 +12,6 @@ set fallback
 # Install Python dependencies.
 install:
     pdm install
-    [ -x "$(command -v to-html)" ] || cargo install --git https://github.com/Aloso/to-html --branch main to-html
 
 ###########
 # Recipes #
diff --git a/examples/src/examples/filtering.py b/examples/src/examples/filtering.py
@@ -17,10 +17,10 @@ def name_filter():
             ["a.rs", "b.rs", "c.rs", "a.jpg", "b.jpg", "c.jpeg"],
         )
     ) as bench:
-        write_out("--only='(a|c)'", r"--exclude='\.jpe?g'", bench=bench, dest_name="on")
+        write_out("--only=(a|c)", r"--exclude=\.jpe?g", bench=bench, dest_name="on")
         write_out(bench=bench, dest_name="off")
         write_out(
-            r"--exclude='\.jpe?g'",
+            r"--exclude=\.jpe?g",
             "a.jpg",
             cwd=bench,
             include_bench=False,
diff --git a/examples/src/examples/utils/io.py b/examples/src/examples/utils/io.py
@@ -14,9 +14,6 @@ def write_content(dest_path: str, content: str):
     :param content: the content to write inside the file
     """
 
-    if not content.endswith("\n"):
-        content += "\n"
-
     dest_path = DOCS_EXAMPLES / dest_path
     if not dest_path.parent.exists():
         dest_path.parent.mkdir(mode=0o755, parents=True)
diff --git a/examples/src/examples/utils/main.py b/examples/src/examples/utils/main.py
@@ -2,7 +2,7 @@
 import shutil
 from pathlib import Path
 
-from examples.utils.to_html import run_to_html
+from examples.utils.pls import run_pls
 from examples.utils.io import write_content
 
 
@@ -31,7 +31,7 @@ def write_out(
     args = list(args)
     if bench and include_bench:
         args.append(str(bench.absolute()))
-    content = run_to_html(args, **kwargs)
+    content = run_pls(args, **kwargs)
 
     out_file = f"{func_name}/{dest_name}.mdx"
     print(f"Writing MDX to '{out_file}'.")
diff --git a/examples/src/examples/utils/pls.py b/examples/src/examples/utils/pls.py
@@ -0,0 +1,26 @@
+from decouple import config
+
+from examples.utils.sub import run_cmd
+
+
+def run_pls(args: list[str], **kwargs) -> str:
+    """
+    Run a ``pls`` command and return the output with ANSI codes.
+
+    It assumes the project root to be the working directory and that a release
+    build of ``pls`` is present on the ``$PATH``.
+
+    All keyword arguments are forwarded as-is to ``run_cmd``.
+
+    :return: the output of the ``pls`` command
+    """
+
+    pls_bin = config("PLS_BIN", default="pls")
+    cmd = [pls_bin, *args]
+    print(f"Running command {cmd}")
+
+    env = kwargs.pop("env", {})
+    if "NO_COLOR" not in env:
+        env["CLICOLOR_FORCE"] = "true"
+    proc = run_cmd(cmd, env=env, **kwargs)
+    return f'```ansi frame="none"\n{proc.stdout}```\n'
diff --git a/examples/src/examples/utils/to_html.py b/examples/src/examples/utils/to_html.py

Original file line number	Diff line number	Diff line change
`@@ -47,7 +47,9 @@ pre.terminal p {`
`47`	`47`	`overflow-x: auto;`
`48`	`48`	`}`
`49`	`49`
`50`		`-div.expressive-code + pre.terminal {`
	`50`	`+/* Join output code block into its preceding command block */`
	`51`	`+div.expressive-code:has(figure.is-terminal)`
	`52`	`+ + div.expressive-code:not(:has(figure.is-terminal)) {`
`51`	`53`	`margin-top: 0;`
`52`		`- border-width: 1px 0 0 0;`
	`54`	`+ border-top: 1px solid var(--sl-color-gray-4);`
`53`	`55`	`}`
Original file line number	Diff line number	Diff line change
`@@ -3,7 +3,7 @@ span.math {`
`3`	`3`	`font-style: italic;`
`4`	`4`	`}`
`5`	`5`
`6`		`-figcaption.header:has(span.sr-only) ~ pre .ec-line .code::before {`
	`6`	`+pre[data-language="bash"] .ec-line .code::before {`
`7`	`7`	`content: "$ ";`
`8`	`8`	`opacity: 0.5;`
`9`	`9`	`}`