@thallylabs/migrate 0.2.40 → 0.2.42

package/README.md

@@ -10,6 +10,12 @@ ordered navigation and binary assets), or uses ordinary local fetching. Hosted
 callers must inject their own network-safe text/capture and binary boundaries.
 No browser, model, credentials, sandbox or publishing provider is bundled here.
 
+Default page requests advertise HTML to retain rendered content and declared
+alternates. An explicit same-origin, same-route Markdown alternate shares the
+article's destination; the rendered article takes precedence even when the
+Markdown URL was discovered first or restored from an interrupted checkpoint.
+Independent pages still report destination collisions.
+
 Server applications should import `@thallylabs/migrate/svg-policy` for the passive
 SVG validator, or `@thallylabs/migrate/url-migration` for the URL runner, renderer
 and their types. These independent entries avoid tracing repository cloning and
@@ -99,8 +105,13 @@ Missing primary counterparts and projected path collisions require review; the
 engine does not invent translations. Fresh HTML captures also observe `html lang`; conflicting or unsupported
 language evidence requires review. Capture adapters can supply `locale` when
 no language is declared in HTML or identified by the scoped URL path.
-The `url-evidence-v6` converter rejects earlier journals: replay retained raw
+The `url-evidence-v7` converter rejects earlier journals: replay retained raw
 captures into a new journal rather than relabelling previously hashed pages.
+Distinct observed redirect routes can retain their own sidebar titles through
+noindex page metadata and portable internal redirects to the captured article.
+Conflicting labels on the same route still require review. Markdown image and
+link destinations are localized by source spans, including escaped query strings,
+without changing matching labels, titles, or fenced examples.
 
 `stopReason` distinguishes a resumable `capture-limit` from hard `page-limit`
 or `byte-limit` outcomes. Hosts must not automatically retry a hard limit as an
@@ -148,7 +159,8 @@ renderer, so it always produces a clear warning naming the spec instead of
 disappearing.
 
 `METHOD /path` entries (`"POST /v2/keys.createKey"`) under a container that
-binds an `openapi` spec become `api.groups` on the tab that spec binds to:
+binds an `openapi` spec become pages of the site (see the next paragraph) or,
+where that is not possible, `api.groups` on the tab that spec binds to:
 nested groups, icons and authored order are kept, and page entries stay in the
 tab's own groups (a group that mixes pages and operations is split, so the
 sidebar lists the API groups after the page groups). Operations written
@@ -178,8 +190,55 @@ site imported by URL, cannot be placed: one warning says they were not added to
 operations still have their pages. This is separate from a `directory`'s flat
 operation list, which still only drives the endpoint redirects.
 
+Mintlify serves one generated page per operation a navigation container lists,
+at `/<directory>/<first tag>/<summary>` (`directory` is the reference's
+`{ source, directory }` folder, `api-reference` when it is a plain string).
+Each such operation becomes an MDX page at that path under `src/content`, so it
+keeps its URL, sidebar entry, eyebrow and previous/next links. Its frontmatter is
+the summary as `title` (else the operation id, else `METHOD /path`), the first
+sentence of the description as `description` (the title when there is none), and
+`openapi: "<spec file> METHOD /path"`; the body is empty. `descriptionPlacement: operation`
+keeps that short summary for search and metadata while the runtime renders the
+full operation description as Markdown, including every paragraph and warning.
+The tab that listed the
+operations is an ordinary page tab, kept where it was among its siblings and
+labelled as they are (`Product: API reference`), whose groups are the authored
+ones, nesting and order kept, each operation replaced by its page. Tabs that were
+separate in the source are never merged, even when they share a spec. The spec
+is bound once per spec file in a hidden tab (`OpenAPI: <spec>`, the same as for a
+spec only a page names), which is what the pages' `openapi:` frontmatter resolves
+against; the renderer serves no `/api/` page, sitemap entry or search record for it. A remote spec's pages
+and tab are made by `hydrateRemoteApiSpecs` once it is downloaded; a download
+that fails leaves no tab and no page, as before. An operation the spec withholds
+(`x-hidden`, `x-excluded`) gets no page, nor does one listed only under a
+`hidden` group or an access-restricted container (such groups are left out of
+the tab, as above). Of two operations with the same tag and
+summary the first listed keeps the URL and one warning names the others; an
+authored page at that URL keeps it. Nothing is redirected from these URLs and a
+link to one stays as written; a link to a tag folder or to an address under the
+directory that matches no page goes to a page, and a folder of pages with no page
+of its own opens on its first page, as in any other navigation. The operations
+fall back to `api.groups` on an API tab, as described above, when the containers
+that share a tab disagree on the directory, the directory cannot be a folder name,
+the spec has none of the listed operations, or the tab is bound to another spec.
+A reference that lists no operation (Mintlify generated every endpoint) is not
+affected. Operations whose path item is a local `$ref` are read as the renderer
+reads them (hidden or excluded on any level of the reference withholds them).
+The renderer tries the first visible API tab's spec first for a bare
+`openapi: "METHOD /path"` page; when converting a tab to pages stops its spec being
+that one, each bare reference to an operation the converted spec defines is
+written with that spec's path in front, so it still renders the same operation.
+
 Mintlify `styling.eyebrows: "breadcrumbs"` becomes `eyebrow: "path"` (the full
 group path above the page title); `"section"` or no setting writes nothing.
+Mintlify sources also get `smartQuotes: true`, because Mintlify renders straight
+quotes in prose as curly ones; the setting leaves code, heading ids, Markdown and
+`llms.txt` as written.
+
+Thally leaves out the sidebar heading of a group named after its tab or dropdown, because
+the collection already names it. Mintlify keeps that heading, so a source with such a group
+(an `API reference` dropdown whose first group is also `API reference`) gets
+`navigation.groupHeadings: "all"`. A source without one gets nothing.
 
 Page `openapi:` frontmatter with a spec prefix
 (`openapi: "specs/openapi-b.yaml GET /widgets/{id}"`) is rewritten to where the
@@ -199,7 +258,8 @@ no operation points to that section's overview page instead, and one warning
 lists the affected links (up to ten). A link to an address the site answers
 itself (a guide authored inside an API directory, trailing slash or `/index` or
 not, or the source of an authored redirect) is never rewritten. A spec that
-Mintlify mounted under a `directory` also gets a redirect from each endpoint URL that directory served,
+Mintlify mounted under a `directory` also gets a redirect from each endpoint URL that directory served
+(not the operations a container lists, which are pages at those URLs),
 to the matching endpoint page, and never to an operation the published spec
 withholds with `x-hidden` or `x-excluded`. A remote spec gets every directory
 each of its tabs mounted it under, limited to the operations the navigation
@@ -244,6 +304,15 @@ whose address has a `+ ? ( ) [ ] { }` character (a `directory` such as
 spec or a downloaded spec is left out instead, and one warning lists the first
 ten of them.
 
+A Mintlify page whose frontmatter `url` is a web address is a link in the
+source sidebar. It is imported as a page that is kept out of the sitemap, stays
+in the navigation, and has a redirect from its path to that address. That
+redirect is added after the checks above, because hiding the page is its
+purpose; a `url` that is not an `http(s)` address is ignored. The home page
+(`index.mdx` or `introduction.mdx`) is served at `/` and at `/introduction`, so
+both redirect, and the redirect from `/` replaces the generated one to the first
+page. A redirect for `/` that the source site wrote stays, and a warning says so.
+
 A repository is limited to 5,000 documentation files and, separately, 5,000
 asset files. Past that, files are kept in navigation order with the default
 version first, then pages not listed in navigation, and one warning counts and

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { M as MigrationPage, a as MigrationAsset, b as MigrationNavigationGroup, R as RenderedMigrationFile, c as MigrationWarning, d as MigrationFetcher, e as MigrationPlatform, f as MigrationBundle, g as MigrationDocsConfig } from './url-run-DFnoqEi-.js';
-export { h as MigrationCapture, i as MigrationCaptureProvider, j as MigrationCaptureState, k as MigrationCapturedAsset, l as MigrationEvidence, m as MigrationFetchRequest, n as MigrationFetchResponse, o as MigrationJournalAsset, p as MigrationNavigationOccurrence, q as MigrationNavigationTab, U as UrlMigrationCheckpoint, r as UrlMigrationCheckpointDelta, s as UrlMigrationIssue, t as UrlMigrationRecord, u as UrlMigrationRun, v as UrlMigrationRunOptions, w as UrlMigrationValidation, x as classifyMigrationResponse, y as mergeMigrationConfig, z as renderMigrationFiles, A as runUrlMigration, B as validateUrlMigration } from './url-run-DFnoqEi-.js';
+import { M as MigrationPage, a as MigrationAsset, b as MigrationNavigationGroup, R as RenderedMigrationFile, c as MigrationWarning, d as MigrationFetcher, e as MigrationPlatform, f as MigrationBundle, g as MigrationDocsConfig, E as EndpointTabSlot } from './url-run-CPzQfjRW.js';
+export { h as MigrationCapture, i as MigrationCaptureProvider, j as MigrationCaptureState, k as MigrationCapturedAsset, l as MigrationEvidence, m as MigrationFetchRequest, n as MigrationFetchResponse, o as MigrationJournalAsset, p as MigrationNavigationOccurrence, q as MigrationNavigationTab, U as UrlMigrationCheckpoint, r as UrlMigrationCheckpointDelta, s as UrlMigrationIssue, t as UrlMigrationRecord, u as UrlMigrationRun, v as UrlMigrationRunOptions, w as UrlMigrationValidation, x as classifyMigrationResponse, y as mergeMigrationConfig, z as renderMigrationFiles, A as runUrlMigration, B as validateUrlMigration } from './url-run-CPzQfjRW.js';
 export { isPassiveSvg } from './svg-policy.js';
 
 /**
@@ -171,6 +171,14 @@ interface MintlifyNavigationResult {
     referenceAccess: Array<MintlifyReferenceAccess>;
     /** `sourceRef` mounts under a restricted container; never resolved, so nothing of theirs is imported. */
     gatedSourceRefs: Array<string>;
+    /**
+     * The API tabs that list operations and nothing else, which `docsConfig.tabs` leaves out: each with the navigation container that
+     * owns it and the place it held among the tabs. Only produced with `operationGroups`; the spec binding puts such a tab back as a page tab.
+     */
+    apiTabSlots: Array<{
+        container: object;
+        slot: EndpointTabSlot;
+    }>;
     warnings: Array<MigrationWarning>;
 }
 interface MintlifyProjectionOptions {