@carlesandres/house 0.4.9 → 0.4.10

package/CHANGELOG.md

@@ -6,6 +6,17 @@ The publish workflow (`.github/workflows/publish.yml`) runs on the `release: pub
 
 ## [Unreleased]
 
+## [0.4.10] — 2026-06-14
+
+### Added
+
+- Active theme selection is now persisted globally, with hardened config saving that preserves symlinked config files.
+
+### Changed
+
+- Sidebar parent paths now middle-truncate in deep trees to keep filenames scannable.
+- Markdown discovery now uses an extension allow-list for supported markdown file types.
+
 ## [0.4.9] — 2026-06-09
 
 ### Fixed
@@ -259,7 +270,7 @@ The v1 MVP, published as `@carlesandres/openmdr` on npm.
 
 ### Added — discovery
 
-- Recursive walk from the path argument (or cwd), `.md` / `.markdown` / `.mdx` only.
+- Recursive walk from the path argument (or cwd), limited to markdown extensions.
 - Honors `.gitignore` (root + nested).
 - Hard-skips `node_modules`, `.git`, `.venv` (always, even with `--all`).
 - Does not follow symlinks.
@@ -294,7 +305,8 @@ The v1 MVP, published as `@carlesandres/openmdr` on npm.
 
 Search, stdin, URL fetching, cross-file link following, `$EDITOR` hand-off, syntax highlighting, persistent config, OS-appearance auto-detect, single-binary distribution (issue [#2](https://github.com/carlesandres/openmdr/issues/2)), Homebrew tap. All tracked.
 
-[Unreleased]: https://github.com/carlesandres/house/compare/v0.4.9...HEAD
+[Unreleased]: https://github.com/carlesandres/house/compare/v0.4.10...HEAD
+[0.4.10]: https://github.com/carlesandres/house/compare/v0.4.9...v0.4.10
 [0.4.9]: https://github.com/carlesandres/house/compare/v0.4.8...v0.4.9
 [0.4.8]: https://github.com/carlesandres/house/compare/v0.4.7...v0.4.8
 [0.4.7]: https://github.com/carlesandres/house/compare/v0.4.6...v0.4.7

package/README.md

@@ -71,7 +71,7 @@ house --serve README.md
 | `--focus <mode>`     | `filter`          | Startup focus: `sidebar`, `reader`, or `filter`. `filter` opens the sidebar filter prompt immediately.       |
 | `--serve`            | off               | Serve the positional path as HTML in the browser (skips TUI)                                                 |
 | `--port <N>`         | OS-assigned       | Port for `--serve`                                                                                           |
-| `--no-mdx`           | off               | Exclude `.mdx` files from discovery                                                                          |
+| `--ext <list>`       | none              | Include extra file extensions (comma-separated)                                                               |
 | `--no-update-check`  | off               | Suppress the "newer version available" check (also via `NO_UPDATE_NOTIFIER=1`)                               |
 | `--config-path`      | —                 | Print the resolved config-file path and exit                                                                 |
 | `-h`, `--help`       | —                 | Show help and exit                                                                                           |
@@ -91,22 +91,22 @@ Run `house --config-path` to print the exact location.
 # ~/.config/house/config.toml
 theme = "tokyonight"
 tone  = "dark"
-mdx   = true
+extensions = []
 show  = ["hidden", "gitignored"]
 focus = "filter"
 defaultRoot = "cwd" # or "git"
 ```
 
-Supported keys: `theme`, `tone`, `mdx`, `show`, `focus`, `defaultRoot`.
+Supported keys: `theme`, `tone`, `extensions`, `show`, `focus`, `defaultRoot`.
 
 `show` is a list of normally-skipped categories to opt into. Known categories: `hidden` (dot-prefixed entries), `gitignored` (entries matched by a `.gitignore`). Default is the empty list. Hard skips (`node_modules`, `.git`, `.venv`) always apply.
 
 Precedence, highest to lowest:
 
-1. CLI flags (`--theme`, `--tone`, `--no-mdx`, `--show`, `--focus`, `--root`)
-2. Env vars (`HOUSE_THEME`, `HOUSE_TONE`, `HOUSE_MDX`, `HOUSE_SHOW`, `HOUSE_FOCUS`, `HOUSE_DEFAULT_ROOT`)
+1. CLI flags (`--theme`, `--tone`, `--ext`, `--show`, `--focus`, `--root`)
+2. Env vars (`HOUSE_THEME`, `HOUSE_TONE`, `HOUSE_EXTENSIONS`, `HOUSE_SHOW`, `HOUSE_FOCUS`, `HOUSE_DEFAULT_ROOT`)
 3. Config file
-4. Built-in defaults (`opencode` / `dark` / `mdx = true` / `show = []` / `focus = "filter"` / `defaultRoot = "cwd"`)
+4. Built-in defaults (`opencode` / `dark` / `extensions = []` / `show = []` / `focus = "filter"` / `defaultRoot = "cwd"`)
 
 `HOUSE_SHOW` takes a comma-separated list (`HOUSE_SHOW=hidden,gitignored`). For `show` specifically, each source completely replaces the next — categories don't merge across layers. Press `shift+a` in the TUI to round-trip between the configured set and the full vocabulary without editing config.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@carlesandres/house",
-		"version": "0.4.9",
+	"version": "0.4.10",
 	"description": "TUI-first markdown reader on opentui",
 	"type": "module",
 	"license": "MIT",

package/src/Browser.tsx

@@ -45,6 +45,8 @@ import { startServer, type ServerHandle } from "./serve/server.ts"
 import { colors, setActiveTheme } from "./theme/colors.ts"
 import { themeAtom } from "./theme/atom.ts"
 import { themeDefinitions, getThemeDefinition } from "./theme/registry.ts"
+import { saveThemePreference } from "./config/save.ts"
+import { middleTruncate } from "./ui/middleTruncate.ts"
 
 export type SidebarMode = "auto" | "on" | "off"
 export type StartupFocus = "sidebar" | "reader" | "filter"
@@ -362,6 +364,12 @@ export const Browser = ({
 		if (!next) return
 		setActiveTheme(next, theme.tone)
 		setTheme({ id: next.id, tone: theme.tone })
+		void saveThemePreference({ theme: next.id, tone: theme.tone }).catch((err) => {
+			pushFooterNotice("theme not saved")
+			process.stderr.write(
+				`house: failed to save theme preference: ${err instanceof Error ? err.message : String(err)}\n`,
+			)
+		})
 		pushFooterNotice(`theme: ${next.name}`)
 	}
 
@@ -370,6 +378,12 @@ export const Browser = ({
 		const def = getThemeDefinition(theme.id)
 		if (def) setActiveTheme(def, nextTone)
 		setTheme({ id: theme.id, tone: nextTone })
+		void saveThemePreference({ theme: theme.id, tone: nextTone }).catch((err) => {
+			pushFooterNotice("theme not saved")
+			process.stderr.write(
+				`house: failed to save theme preference: ${err instanceof Error ? err.message : String(err)}\n`,
+			)
+		})
 		pushFooterNotice(`tone: ${nextTone}`)
 	}
 
@@ -967,7 +981,12 @@ export const Browser = ({
 						<text key={file.path} wrapMode="none" style={rowStyle}>
 							<span style={{ fg: basenameFg }}>{basename}</span>
 							{parent !== "" && (
-								<span style={{ fg: colors.textMuted }}>{`${separator}${parent}`}</span>
+								<span style={{ fg: colors.textMuted }}>
+									{middleTruncate(
+										`${separator}${parent}`,
+										Math.max(0, sidebarTextWidth - basename.length),
+									)}
+								</span>
 							)}
 						</text>
 					)

package/src/cli/argv.ts

@@ -28,8 +28,8 @@ export interface ParsedArgs {
 	 *  probe and the "update available" notice. Mirrors the
 	 *  `NO_UPDATE_NOTIFIER` env var so opt-out is reachable without env state. */
 	readonly noUpdateCheck: boolean
-	/** True when `--no-mdx` was passed: exclude `.mdx` files from discovery. */
-	readonly noMdx: boolean
+	/** Raw value of `--ext [list]`, or null if absent. Comma-separated list. */
+	readonly extensions: string | null
 	/** Value of `--focus <mode>` (`sidebar`, `reader`, `filter`), or null.
 	 *  Validated by the boot layer. */
 	readonly focus: string | null
@@ -54,7 +54,7 @@ const createProgram = () =>
 		.option("--config-path")
 		.option("--sidebar [mode]")
 		.option("--no-update-check")
-		.option("--no-mdx")
+		.option("--ext [list]")
 		.option("--focus [mode]")
 		.option("--show [list]")
 		.option("--root [dir]")
@@ -71,6 +71,7 @@ const VALUE_FLAGS: ReadonlySet<string> = new Set([
 	"--focus",
 	"--show",
 	"--root",
+	"--ext",
 ])
 
 const REMOVED_VALUE_FLAGS: ReadonlySet<string> = new Set(["--sort"])
@@ -79,7 +80,6 @@ const BOOLEAN_FLAGS: ReadonlySet<string> = new Set([
 	"--serve",
 	"--config-path",
 	"--no-update-check",
-	"--no-mdx",
 	"--help",
 	"-h",
 	"--version",
@@ -128,7 +128,7 @@ export const parseArgv = (argv: readonly string[]): ParsedArgs => {
 		configPath: opts["configPath"] === true,
 		sidebar: stringOrNull(opts["sidebar"]),
 		noUpdateCheck: opts["noUpdateCheck"] === true,
-		noMdx: opts["mdx"] === false,
+		extensions: stringOrNull(opts["ext"]),
 		show: stringOrNull(opts["show"]),
 		focus: stringOrNull(opts["focus"]),
 	}
@@ -157,7 +157,7 @@ options:
   -v, --version  print version and exit
   --config-path  print path to the config file and exit
   --no-update-check  suppress the "newer version available" check (also via NO_UPDATE_NOTIFIER=1)
-  --no-mdx       exclude .mdx files from discovery (default: included)
+	--ext <list>   include extra file extensions (comma-separated)
 
 examples:
   house README.md
@@ -166,6 +166,6 @@ examples:
 
 configuration:
   file: $XDG_CONFIG_HOME/house/config.toml  (default ~/.config/house/config.toml)
-  keys: theme, tone, mdx, show, focus, defaultRoot
-  env:  HOUSE_THEME, HOUSE_TONE, HOUSE_MDX, HOUSE_SHOW, HOUSE_FOCUS, HOUSE_DEFAULT_ROOT
+	  keys: theme, tone, extensions, show, focus, defaultRoot
+	  env:  HOUSE_THEME, HOUSE_TONE, HOUSE_EXTENSIONS, HOUSE_SHOW, HOUSE_FOCUS, HOUSE_DEFAULT_ROOT
   precedence (high → low): flags → env → file → defaults`

package/src/config/load.ts

@@ -19,7 +19,7 @@ import { themeDefinitions } from "../theme/registry.ts"
 export interface HouseConfig {
 	readonly theme: string
 	readonly tone: "dark" | "light"
-	readonly mdx: boolean
+	readonly extensions: readonly string[]
 	/** Default discovery-root strategy when no explicit `--root` flag is passed. */
 	readonly defaultRoot: "cwd" | "git"
 	/** Categories of normally-skipped entries to opt into. See
@@ -34,7 +34,7 @@ export interface HouseConfig {
 export interface CliOverrides {
 	readonly theme: string | null
 	readonly tone: string | null
-	readonly mdx: boolean | null
+	readonly extensions: readonly string[] | null
 	/** When non-null, the parsed `--show` list completely replaces env/file
 	 *  (no per-category merging — sets compose by replacement, like every
 	 *  other CLI override here). `--show ""` sets the empty set. */
@@ -44,7 +44,7 @@ export interface CliOverrides {
 
 const DEFAULT_THEME = "opencode"
 const DEFAULT_TONE: "dark" | "light" = "dark"
-const DEFAULT_MDX = true
+const DEFAULT_EXTENSIONS: readonly string[] = []
 const DEFAULT_ROOT: "cwd" | "git" = "cwd"
 const DEFAULT_SHOW = ""
 const DEFAULT_FOCUS: "sidebar" | "reader" | "filter" = "filter"
@@ -60,7 +60,7 @@ const themeIds = themeDefinitions.map((t) => t.id)
 const KNOWN_FILE_KEYS: ReadonlySet<string> = new Set([
 	"theme",
 	"tone",
-	"mdx",
+	"extensions",
 	"show",
 	"focus",
 	"defaultRoot",
@@ -70,10 +70,8 @@ const schema = Config.all({
 	theme: Config.schema(Schema.Literals(themeIds), "theme"),
 	tone: Config.schema(Schema.Literals(["dark", "light"] as const), "tone"),
 	defaultRoot: Config.schema(Schema.String, "defaultRoot"),
-	// Boolean stored as string literal because providers stringify values
-	// (TOML bools, env vars, CLI flags all flow through as text). Mapped to
-	// a real boolean in `loadConfig` below.
-	mdx: Config.schema(Schema.Literals(["true", "false"] as const), "mdx"),
+	// Comma-separated extension list. Empty string means no extra extensions.
+	extensions: Config.schema(Schema.String, "extensions"),
 	// `show` arrives as a comma-separated string from every provider
 	// (`fileProvider` coerces TOML arrays via `String()`, which produces
 	// `"hidden,gitignored"`). Token-level validation happens in `loadConfig`
@@ -87,7 +85,7 @@ const defaultsProvider = (): ConfigProvider.ConfigProvider =>
 		theme: DEFAULT_THEME,
 		tone: DEFAULT_TONE,
 		defaultRoot: DEFAULT_ROOT,
-		mdx: String(DEFAULT_MDX),
+		extensions: DEFAULT_EXTENSIONS.join(","),
 		show: DEFAULT_SHOW,
 		focus: DEFAULT_FOCUS,
 	})
@@ -205,13 +203,13 @@ const envProvider = (env: Record<string, string | undefined>): ConfigProvider.Co
 	const theme = env["HOUSE_THEME"]
 	const tone = env["HOUSE_TONE"]
 	const defaultRoot = env["HOUSE_DEFAULT_ROOT"]
-	const mdx = env["HOUSE_MDX"]
+	const extensions = env["HOUSE_EXTENSIONS"]
 	const show = env["HOUSE_SHOW"]
 	const focus = env["HOUSE_FOCUS"]
 	if (theme !== undefined) entries.push(["theme", theme])
 	if (tone !== undefined) entries.push(["tone", tone])
 	if (defaultRoot !== undefined) entries.push(["defaultRoot", defaultRoot])
-	if (mdx !== undefined) entries.push(["mdx", mdx])
+	if (extensions !== undefined) entries.push(["extensions", extensions])
 	if (show !== undefined) entries.push(["show", show])
 	if (focus !== undefined) entries.push(["focus", focus])
 	return ConfigProvider.fromUnknown(Object.fromEntries(entries))
@@ -221,7 +219,7 @@ const cliProvider = (overrides: CliOverrides): ConfigProvider.ConfigProvider =>
 	const entries: Array<[string, string]> = []
 	if (overrides.theme !== null) entries.push(["theme", overrides.theme])
 	if (overrides.tone !== null) entries.push(["tone", overrides.tone])
-	if (overrides.mdx !== null) entries.push(["mdx", String(overrides.mdx)])
+	if (overrides.extensions !== null) entries.push(["extensions", overrides.extensions.join(",")])
 	if (overrides.show !== null) entries.push(["show", overrides.show.join(",")])
 	if (overrides.focus !== null) entries.push(["focus", overrides.focus])
 	return ConfigProvider.fromUnknown(Object.fromEntries(entries))
@@ -264,7 +262,7 @@ export const loadConfig = (
 	const cli = options.cli ?? {
 		theme: null,
 		tone: null,
-		mdx: null,
+		extensions: null,
 		show: null,
 		focus: null,
 	}
@@ -300,7 +298,13 @@ export const loadConfig = (
 				theme: raw.theme,
 				tone: raw.tone,
 				defaultRoot,
-				mdx: raw.mdx === "true",
+				extensions:
+					raw.extensions === ""
+						? []
+						: raw.extensions
+								.split(",")
+								.map((s) => s.trim())
+								.filter(Boolean),
 				show: parsed.value,
 				focus: raw.focus,
 			})

package/src/config/save.ts

@@ -0,0 +1,95 @@
+import { dirname } from "node:path"
+import { lstat, mkdir, readFile, realpath, rename, unlink, writeFile } from "node:fs/promises"
+import { defaultConfigPath } from "./load.ts"
+
+export interface ThemePreference {
+	readonly theme: string
+	readonly tone: "dark" | "light"
+}
+
+let saveQueue: Promise<void> = Promise.resolve()
+
+const encodeTomlString = (value: string): string => JSON.stringify(value)
+
+const upsertTopLevelString = (raw: string, key: keyof ThemePreference, value: string): string => {
+	const encoded = encodeTomlString(value)
+	const lines = raw.split("\n")
+	const keyPattern = new RegExp(`^(\\s*)${key}\\s*=.*$`)
+	let inTopLevel = true
+	let insertAt = lines.length
+
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i]!
+		if (/^\s*\[[^\]]+\]\s*(?:#.*)?$/.test(line)) {
+			inTopLevel = false
+			insertAt = Math.min(insertAt, i)
+		}
+		if (!inTopLevel) continue
+		const match = keyPattern.exec(line)
+		if (match) {
+			lines[i] = `${match[1]}${key} = ${encoded}`
+			return lines.join("\n")
+		}
+	}
+
+	const insertion = `${key} = ${encoded}`
+	if (insertAt === lines.length) {
+		if (lines.length === 0 || lines[lines.length - 1] !== "") return `${raw}\n${insertion}\n`
+		lines.splice(lines.length - 1, 0, insertion)
+		return lines.join("\n")
+	}
+
+	lines.splice(insertAt, 0, insertion)
+	return lines.join("\n")
+}
+
+const updateThemePreferenceToml = (raw: string, record: ThemePreference): string => {
+	// Validate the existing file before preserving and editing its text. If the
+	// user has malformed TOML, fail loudly rather than replacing it wholesale.
+	Bun.TOML.parse(raw)
+	return upsertTopLevelString(upsertTopLevelString(raw, "theme", record.theme), "tone", record.tone)
+}
+
+const resolveWritableConfigPath = async (path: string): Promise<string> => {
+	try {
+		const stat = await lstat(path)
+		if (stat.isSymbolicLink()) return await realpath(path)
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err
+	}
+	return path
+}
+
+const writeThemePreference = async (record: ThemePreference, path: string): Promise<void> => {
+	const targetPath = await resolveWritableConfigPath(path)
+	path = targetPath
+	const tmp = `${path}.${process.pid}.${Date.now()}.tmp`
+	try {
+		await mkdir(dirname(path), { recursive: true })
+		let next = `theme = ${encodeTomlString(record.theme)}\ntone = ${encodeTomlString(record.tone)}\n`
+		try {
+			const raw = await readFile(path, "utf8")
+			next = updateThemePreferenceToml(raw, record)
+		} catch (err) {
+			if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err
+		}
+		await writeFile(tmp, next, "utf8")
+		await rename(tmp, path)
+	} catch (err) {
+		try {
+			await unlink(tmp)
+		} catch {
+			// best-effort cleanup
+		}
+		throw err
+	}
+}
+
+export const saveThemePreference = async (
+	record: ThemePreference,
+	path = defaultConfigPath(),
+): Promise<void> => {
+	const run = saveQueue.catch(() => {}).then(() => writeThemePreference(record, path))
+	saveQueue = run.catch(() => {})
+	return run
+}

package/src/discovery/walk.ts

@@ -24,8 +24,9 @@ export interface WalkOptions {
 	 *  entries. Order is irrelevant — semantics are set membership. Hard
 	 *  skips (`node_modules`, `.git`, `.venv`) always apply. */
 	readonly show?: Iterable<ShowCategory>
-	/** Include `.mdx` files alongside `.md`/`.markdown`. Default `true`. */
-	readonly mdx?: boolean
+	/** Additional file extensions to include alongside `.md` / `.markdown`.
+	 *  Values may include or omit the leading dot. */
+	readonly extensions?: Iterable<string>
 	/** Non-fatal subtree read errors. Root-level failures still error the walk. */
 	readonly onWarning?: ((warning: DiscoveryWarning) => void) | null
 }
@@ -35,10 +36,14 @@ export class DiscoveryError extends Data.TaggedError("DiscoveryError")<{
 	readonly cause: unknown
 }> {}
 
-const MARKDOWN_EXTENSIONS = new Set([".md", ".markdown", ".mdx"])
-const MARKDOWN_EXTENSIONS_NO_MDX = new Set([".md", ".markdown"])
+const BASE_EXTENSIONS = new Set([".md", ".markdown"])
 const HARD_SKIP_DIRS = new Set(["node_modules", ".git", ".venv"])
 
+const normalizeExtension = (ext: string): string => {
+	const trimmed = ext.trim().toLowerCase()
+	return trimmed.startsWith(".") ? trimmed : `.${trimmed}`
+}
+
 interface IgnoreLevel {
 	readonly dir: string
 	readonly ig: Ignore
@@ -93,7 +98,7 @@ async function* walkDirGen(
 	dirPath: string,
 	rootPath: string,
 	parentLevels: readonly IgnoreLevel[],
-	opts: { showHidden: boolean; showGitignored: boolean; mdx: boolean },
+	opts: { showHidden: boolean; showGitignored: boolean; extensions: ReadonlySet<string> },
 	onWarning: ((warning: DiscoveryWarning) => void) | null,
 	signal: AbortSignal,
 ): AsyncGenerator<FileEntry, void, void> {
@@ -136,7 +141,7 @@ async function* walkDirGen(
 
 		if (!entry.isFile()) continue
 		if (!opts.showHidden && entry.name.startsWith(".")) continue
-		const allowed = opts.mdx ? MARKDOWN_EXTENSIONS : MARKDOWN_EXTENSIONS_NO_MDX
+		const allowed = opts.extensions
 		if (!allowed.has(extname(entry.name).toLowerCase())) continue
 		if (!opts.showGitignored && isIgnored(entryPath, false, levels)) continue
 
@@ -155,7 +160,7 @@ async function* walkDirGen(
  * at its next `signal.aborted` check.
  *
  * Rules (see DESIGN.md §6):
- * - Extensions: `.md`, `.markdown`, and `.mdx` (unless `mdx: false`).
+ * - Extensions: `.md`, `.markdown`, plus configured extras.
  * - Hard skips (always): `node_modules`, `.git`, `.venv`.
  * - Hidden files/dirs (leading `.`) skipped unless `show` contains `"hidden"`.
  * - `.gitignore` honored, including nested `.gitignore` files.
@@ -168,10 +173,12 @@ export const walk = (
 ): Stream.Stream<FileEntry, DiscoveryError> => {
 	const absRoot = resolve(root)
 	const show = new Set<ShowCategory>(options.show ?? [])
+	const extensions = new Set(BASE_EXTENSIONS)
+	for (const ext of options.extensions ?? []) extensions.add(normalizeExtension(ext))
 	const opts = {
 		showHidden: show.has("hidden"),
 		showGitignored: show.has("gitignored"),
-		mdx: options.mdx ?? true,
+		extensions,
 	}
 	const onWarning = options.onWarning ?? null
 	const controller = new AbortController()

package/src/index.tsx

@@ -106,7 +106,7 @@ interface DiscoverShellProps {
 	 *  and the full vocabulary; the underlying categories remain
 	 *  independent everywhere else. */
 	readonly initialShow: readonly ShowCategory[]
-	readonly mdx: boolean
+	readonly extensions: readonly string[]
 	readonly maxWidth: number | null
 	readonly sidebarMode: SidebarMode
 	readonly startupFocus: StartupFocus
@@ -116,7 +116,7 @@ export const DiscoverShell = ({
 	target,
 	initialQuery,
 	initialShow,
-	mdx,
+	extensions,
 	maxWidth,
 	sidebarMode,
 	startupFocus,
@@ -145,7 +145,7 @@ export const DiscoverShell = ({
 		countRef.current = 0
 		const warnedProgram = walk(target, {
 			show,
-			mdx,
+			extensions,
 			onWarning: ({ path }) => {
 				const relativePath = relative(resolve(target), path)
 				setSkippedDirCount((prev) => prev + 1)
@@ -179,7 +179,7 @@ export const DiscoverShell = ({
 		return () => {
 			Effect.runFork(Fiber.interrupt(fiber))
 		}
-	}, [target, show, mdx])
+	}, [target, show, extensions])
 
 	const discoveryStatus =
 		scanError ??
@@ -268,9 +268,13 @@ if (import.meta.main) {
 			cli: {
 				theme: args.theme,
 				tone: args.tone,
-				// --no-mdx is a one-way override: present means "off". When
-				// absent, fall through to env/file/default.
-				mdx: args.noMdx ? false : null,
+				extensions:
+					args.extensions === null
+						? null
+						: args.extensions
+								.split(",")
+								.map((s) => s.trim())
+								.filter(Boolean),
 				// `--show` replaces env/file when present (set semantics —
 				// no per-category merge across sources). `null` falls through.
 				show: cliShow,
@@ -284,7 +288,7 @@ if (import.meta.main) {
 		console.error(`house: ${formatConfigError(err)}`)
 		process.exit(2)
 	})
-	const { theme: themeId, tone, mdx, show, focus: startupFocus, defaultRoot } = config
+	const { theme: themeId, tone, extensions, show, focus: startupFocus, defaultRoot } = config
 	const themeDef = getThemeDefinition(themeId)
 	if (themeDef === undefined) {
 		// Unreachable: Config.schema validated themeId against themeDefinitions.
@@ -368,7 +372,7 @@ if (import.meta.main) {
 			tone,
 			maxWidth,
 			show,
-			mdx,
+			extensions,
 			sidebarMode,
 			startupFocus,
 			updateCheck: !args.noUpdateCheck,
@@ -383,7 +387,7 @@ interface TuiBootOptions {
 	readonly tone: "dark" | "light"
 	readonly maxWidth: number | null
 	readonly show: readonly ShowCategory[]
-	readonly mdx: boolean
+	readonly extensions: readonly string[]
 	readonly sidebarMode: SidebarMode
 	readonly startupFocus: StartupFocus
 	/** Run the npm-registry probe and surface the "update available" notice.
@@ -398,7 +402,7 @@ async function runTui({
 	tone,
 	maxWidth,
 	show,
-	mdx,
+	extensions,
 	sidebarMode,
 	startupFocus,
 	updateCheck,
@@ -441,7 +445,7 @@ async function runTui({
 				target={discoveryRoot}
 				initialQuery={initialQuery}
 				initialShow={show}
-				mdx={mdx}
+				extensions={extensions}
 				maxWidth={maxWidth}
 				sidebarMode={sidebarMode}
 				startupFocus={startupFocus}

package/src/layout/sidebarRow.ts

@@ -10,20 +10,15 @@
  * selected row); a future auto-scroll on the selected sidebar row can carry
  * the same information without altering layout for the rest.
  *
- * Truncation policy (head-elide, segment-aware):
- *   - Full parent fits → render whole.
- *   - Else drop leading segments one at a time, prefixed with `…/`, until
- *     the remainder fits — never chops a segment mid-character.
- *   - When even the tail segment with `…/` overflows, drop the marker.
- *   - When the tail segment alone overflows, hard-truncate it from its head
- *     (leading `…`) as a last resort.
- *
- * Why head-elide: the immediate parent is the segment closest to the file
- * and the most universally meaningful one when context shrinks.
+ * Truncation policy: the basename stays whole when possible; the parent path
+ * middle-truncates into `a/…/z`-style output once it exceeds the remaining
+ * width. This preserves both the start and the end of the path, which is
+ * usually what users need to disambiguate nested docs.
  */
 
+import { middleTruncate } from "../ui/middleTruncate.ts"
+
 export const SIDEBAR_ROW_SEPARATOR = " "
-const ELISION_PREFIX = "…/"
 const MIN_PARENT_BUDGET = 3
 
 export interface SidebarRowParts {
@@ -54,18 +49,7 @@ export const formatSidebarRow = (relativePath: string, totalWidth: number): Side
 		return row(basename, parentFull)
 	}
 
-	const segments = parentFull.split("/")
-	for (let k = segments.length - 1; k >= 1; k--) {
-		const candidate = ELISION_PREFIX + segments.slice(segments.length - k).join("/")
-		if (candidate.length <= remaining) return row(basename, candidate)
-	}
-
-	// Even one segment with the `…/` marker doesn't fit. Try without the marker.
-	const tail = segments[segments.length - 1]!
-	if (tail.length <= remaining) return row(basename, tail)
-
-	// Hard-chop the tail segment from its head as a last resort.
-	return row(basename, "…" + tail.slice(tail.length - remaining + 1))
+	return row(basename, middleTruncate(parentFull, remaining))
 }
 
 const row = (basename: string, parent: string): SidebarRowParts => ({

package/src/ui/middleTruncate.ts

@@ -0,0 +1,27 @@
+/**
+ * Middle truncation for technical strings.
+ *
+ * Keeps the start and end of a string visible while compressing the middle
+ * to a single ellipsis glyph (`…`). Use for paths, IDs, branch names, and
+ * other values whose head and tail both matter.
+ */
+
+export interface MiddleTruncateOptions {
+	readonly ellipsis?: string
+}
+
+export const middleTruncate = (
+	value: string,
+	width: number,
+	options: MiddleTruncateOptions = {},
+): string => {
+	const ellipsis = options.ellipsis ?? "…"
+	if (width <= 0) return ""
+	if (value.length <= width) return value
+	if (width <= ellipsis.length) return value.slice(0, width)
+
+	const available = width - ellipsis.length
+	const left = Math.ceil(available / 2)
+	const right = Math.floor(available / 2)
+	return value.slice(0, left) + ellipsis + value.slice(value.length - right)
+}