Add Mintlify-parity reference renderer

.envrc

@@ -1,6 +1,7 @@
-watch_file shell.nix
+watch_file flake.nix
+watch_file flake.lock
 watch_file pyproject.toml
 
-PATH_add "$PWD/.venv/bin"
+export NIX_CONFIG="experimental-features = nix-command flakes"
 
-use nix
+use flake

.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Install Nix
+        uses: cachix/install-nix-action@v27
+
+      - name: Run unit tests in the pinned dev shell
+        run: nix develop . --command pytest

README.md

@@ -35,6 +35,14 @@ x2mdx asyncapi build-api-pages-from-manifest --manifest fixtures/asyncapi.json -
 x2mdx openrpc build-api-pages-from-manifest --manifest fixtures/openrpc.json --output-dir ./out/openrpc
 ```
 
+Run the tool through the pinned shell so `python`, `pytest`, and `x2mdx` all come from the same environment:
+
+```bash
+direnv allow
+direnv exec . x2mdx list-formats
+direnv exec . pytest
+```
+
 ## JVM Docs
 
 `jvm-docs build-api-pages-from-manifest` consumes a local manifest of Javadoc/Scaladoc jars and renders:
@@ -115,13 +123,20 @@ The intended split is:
 
 ## direnv / Nix
 
-This repo now includes [.envrc](/Users/danielporter/control/.envrc) and [shell.nix](/Users/danielporter/control/shell.nix) so `direnv` can give you a Mintlify-compatible Node runtime.
+This repo includes [`flake.nix`](./flake.nix), [`flake.lock`](./flake.lock), [`.envrc`](./.envrc), and [`shell.nix`](./shell.nix) so the development shell is pinned and reproducible.
 
 Activate it with:
 
 ```bash
 direnv allow
-node -v
+direnv exec . x2mdx list-formats
+direnv exec . pytest
 ```
 
-The shell pins Node 22, which works with Mintlify and avoids the local Node 25 incompatibility.
+The shell pins:
+
+- Node 22 for Mintlify compatibility
+- Python 3.12 plus the runtime and test dependencies used by `x2mdx`
+- the `x2mdx` CLI itself, built from the checked-out source tree
+
+GitHub Actions uses the same flake via `.github/workflows/ci.yml`, so local `direnv` and CI exercise the same bootstrap path.

flake.nix

@@ -0,0 +1,60 @@
+{
+  description = "Reproducible development shell for x2mdx";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.11";
+    flake-utils.url = "github:numtide/flake-utils";
+  };
+
+  outputs = { self, nixpkgs, flake-utils }:
+    flake-utils.lib.eachDefaultSystem (
+      system:
+      let
+        pkgs = import nixpkgs { inherit system; };
+        python = pkgs.python312;
+        pythonPackages = pkgs.python312Packages;
+        pythonEnv = python.withPackages (
+          ps: with ps; [
+            jinja2
+            protobuf
+            pyyaml
+            pytest
+          ]
+        );
+        x2mdx = pythonPackages.buildPythonApplication {
+          pname = "x2mdx";
+          version = "0.1.0";
+          pyproject = true;
+          src = ./.;
+          nativeBuildInputs = with pythonPackages; [
+            setuptools
+            wheel
+          ];
+          propagatedBuildInputs = with pythonPackages; [
+            jinja2
+            protobuf
+            pyyaml
+          ];
+          doCheck = false;
+        };
+      in
+      {
+        packages.default = x2mdx;
+        apps.default = flake-utils.lib.mkApp { drv = x2mdx; };
+
+        devShells.default = pkgs.mkShell {
+          packages = [
+            pkgs.git
+            pkgs.nodejs_22
+            pythonEnv
+            x2mdx
+          ];
+
+          shellHook = ''
+            export PYTHONPATH="$PWD/src''${PYTHONPATH:+:$PYTHONPATH}"
+            echo "x2mdx dev shell ready: node $(node -v), python $(python --version 2>&1)"
+          '';
+        };
+      }
+    );
+}

shell.nix

@@ -1,14 +1 @@
-{ pkgs ? import <nixpkgs> {} }:
-
-pkgs.mkShell {
-  packages = [
-    pkgs.git
-    pkgs.nodejs_22
-    pkgs.python3
-  ];
-
-  shellHook = ''
-    export PATH="$PWD/.venv/bin:$PWD/node_modules/.bin:$PATH"
-    echo "control dev shell ready: node $(node -v)"
-  '';
-}
+(builtins.getFlake (toString ./. )).devShells.${builtins.currentSystem}.default