docmedown 0.1.4 → 0.1.6

package/dist/types/runtime/config-schema.d.ts

@@ -148,6 +148,7 @@ export declare const docConfigSchema: z.ZodObject<{
     description: z.ZodOptional<z.ZodString>;
     version: z.ZodOptional<z.ZodString>;
     rootDoc: z.ZodOptional<z.ZodString>;
+    home: z.ZodOptional<z.ZodString>;
     source: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
         type: z.ZodLiteral<"github">;
         repo: z.ZodString;
@@ -266,6 +267,7 @@ export declare const normalizedDocConfigSchema: z.ZodObject<{
     description: z.ZodOptional<z.ZodString>;
     version: z.ZodOptional<z.ZodString>;
     rootDoc: z.ZodOptional<z.ZodString>;
+    home: z.ZodOptional<z.ZodString>;
     source: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
         type: z.ZodLiteral<"github">;
         repo: z.ZodString;

package/dist/types/runtime/home.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Documentation home resolution.
+ *
+ * Resolution order for the Home action:
+ * 1. Explicit `home` setting (document path/slug, or a link escape hatch).
+ * 2. Root-level README.md, PROJECT.md, ABOUT.md, INDEX.md — case-sensitive pass.
+ * 3. The same candidates again case-insensitively.
+ * 4. The alphabetically first Markdown document in the corpus.
+ *
+ * Documentation inside documentation: when an ancestor documentation manifest is
+ * reachable, Home links to the original (outermost) documentation home instead.
+ */
+export declare const HOME_CANDIDATE_FILES: readonly ["README.md", "PROJECT.md", "ABOUT.md", "INDEX.md"];
+/** How many directory levels upward to probe for an enclosing documentation root. */
+export declare const ORIGINAL_HOME_MAX_ANCESTORS = 3;
+export interface HomeDocumentInput {
+    slug?: string;
+    path?: string;
+}
+export interface HomeConfigInput {
+    home?: string;
+}
+export interface ResolvedHome {
+    kind: "route" | "href";
+    slug?: string;
+    href?: string;
+    /** Set when the home was resolved from an enclosing documentation root. */
+    via?: "ancestor";
+}
+export interface MinimalFetchResponse {
+    ok: boolean;
+    json: () => Promise<unknown>;
+}
+export type MinimalFetch = (input: string) => Promise<MinimalFetchResponse>;
+/**
+ * Resolves the documentation home from a corpus of documents. `docs` accepts
+ * manifest items, sidebar nodes, or bare file paths.
+ */
+export declare function resolveDocumentationHome(docs: HomeDocumentInput[] | null | undefined, config?: HomeConfigInput | null): ResolvedHome | null;
+/**
+ * Detects documentation inside documentation by probing ancestor directories
+ * for an enclosing DocMeDown manifest. Returns the original documentation home
+ * as a page-relative link, or null when no ancestor documentation exists.
+ */
+export declare function findOriginalDocumentationHome(fetchImpl: MinimalFetch, options?: {
+    levels?: number;
+}): Promise<ResolvedHome | null>;

package/dist/types/runtime/provider/DocProvider.d.ts

@@ -1,4 +1,5 @@
 import type React from "react";
+import { type ResolvedHome } from "../home";
 import { type ParsedMarkdown } from "../markdown/parser";
 import { HashRouter } from "../router";
 import { DocSearchIndex } from "../search/search-index";
@@ -22,6 +23,7 @@ interface DocContextType {
     error: string | null;
     prevDoc: NavDocItem | null;
     nextDoc: NavDocItem | null;
+    home: ResolvedHome | null;
     isSearchOpen: boolean;
     setIsSearchOpen: (open: boolean) => void;
     isMobileSidebarOpen: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docmedown",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "The simplest MarkDown documenter yet. CLI & Web Script React SPA documentation engine.",
   "main": "./dist/docmedown.cjs",
   "module": "./dist/docmedown.mjs",
@@ -46,7 +46,7 @@
     "build:docs:watch": "node ./bin/docmedown.js build ./docs --watch",
     "build:offline": "node ./bin/docmedown.js build ./docs",
     "config:docs": "node ./bin/docmedown.js config ./docs/docs.json",
-    "test": "npx tsx --test tests/parser.test.ts tests/scanner.test.ts tests/theme-schema.test.ts tests/runtime-integration.test.ts tests/package-smoke.test.ts tests/hosting.test.ts",
+    "test": "npx tsx --test tests/parser.test.ts tests/scanner.test.ts tests/theme-schema.test.ts tests/runtime-integration.test.ts tests/package-smoke.test.ts tests/hosting.test.ts tests/deploy.test.ts tests/home.test.ts",
     "test:artifacts": "npx tsx --test tests/offline-artifact.test.ts",
     "test:release": "npm run typecheck && npm run lint && npm run test && npm run build && npm run build:docs && npm run test:artifacts && npm pack --dry-run",
     "deploy": "node ./scripts/deploy.mjs",

package/schemas/docs.schema.json

@@ -12,6 +12,11 @@
     "description": { "type": "string" },
     "version": { "type": "string" },
     "rootDoc": { "type": "string", "minLength": 1 },
+    "home": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Documentation home document (path or slug) or an explicit link. Defaults to README.md, PROJECT.md, ABOUT.md, or INDEX.md at the documentation root (case-sensitive pass first, then case-insensitive), then the alphabetically first Markdown document."
+    },
     "source": { "$ref": "#/$defs/source" },
     "theme": { "$ref": "#/$defs/theme" },
     "nav": { "type": "array", "items": { "$ref": "#/$defs/navLink" } },

package/templates/docs.json

@@ -5,6 +5,7 @@
   "description": "Fast, modern documentation created with DocMeDown",
   "version": "1.0.0",
   "rootDoc": "README.md",
+  "home": "README.md",
   "theme": {
     "family": "atlas",
     "density": "comfortable",