Build and reader issues
Start with the exact command, revision, runtime and named file. Preserve source and the last reviewed output before a repair. Direct build clears its selected output; repeated builds are not a safe way to discover which folder you meant.
Establish the failing layer
| Layer | Evidence |
|---|---|
| Runtime | Actual Node/npm versions |
| Input | Checkout, source/data/config paths |
| Builder | Exit and first relevant error |
| Output | Home/deep HTML, assets and index |
| Browser | Actual response and console |
| Host | Deployment artifact and responses |
Node must be 24+ for this pin. Inspect node --version and npm --version in the same terminal/session used for the build. Verify the checkout before installing locked dependencies. An install/build that ran elsewhere does not repair this project.
Metadata and route failures
| Message or symptom | First check |
|---|---|
| Unsupported frontmatter language | Opening delimiter/language |
| YAML parser error | Named file, line and value |
| Duplicate URL | Both source titles/ancestors |
| Blank or unexpected route | Actual title slug |
| Wrong navigation order | Folder integer order |
| Hidden content reachable | Expected built/indexed behavior |
The parser accepts YAML, not ---js, JavaScript, JSON or alternate frontmatter engines. Use plain ---, ---yaml or ---yml; quote values with colon-like syntax and keep booleans/numbers at their intended types. Do not suppress a parse error by discarding unknown metadata or executing imported content.
Duplicate registration names both sources before output deletion. Change the intended title or folder-title structure, inspect all descendant routes, update links and plan legacy redirects where needed. A filename rename alone may not change the route. Later render/filesystem failures do not have the same last-output preservation guarantee.
Page slugs strip non-ASCII characters; heading anchors use a different rule. Hebrew-only/empty title fixtures can reach root or collide; this is not automatic multilingual routing. Copy actual generated permalinks and test a disposable fixture before changing public titles. Validation limits gives observed examples.
Output and assets
| Symptom | Check |
|---|---|
| Build output incomplete | Exit/error and chosen folder |
| Page unstyled | CSS response, prefix and host root |
| Font missing | Local vendor files and font responses |
| Image missing | Static bytes, case and authored URL |
| Download wrong | Exact file bytes and audience |
| Old presentation | Deployed files and caching |
Serve generated output over HTTP instead of opening a file URL. Check actual status, media type and body; 200 with homepage HTML is not a successful CSS, JSON or deep-page response. Confirm case-sensitive asset paths and build-copied bytes. Root-relative authored links are not automatically rewritten for a deployment prefix.
Static/template inputs remain installed engine folders even with --content or --out. Do not assume a custom content tree’s neighboring assets were copied. Build progress/search entry totals are not a reliable unique-page count. Build internals explains the passes.
If only the host looks old, inspect its production branch/artifact, output-directory setting, build status and actual responses before cache purges. Deploy the complete reviewed output, not only one HTML page while leaving stale search/vendor files. Preserve rollback evidence before any destructive host change.
Local preview
| Symptom | Check |
|---|---|
| Invalid preview port | Integer 1-65535 |
| Address already in use | Intended process owning port |
| Connection refused | Preview running on loopback |
| Missing route | Actual built path and 404 status |
| POST rejected | Preview is GET/HEAD only |
The variable is MARKSTACK_PREVIEW_PORT, not generic PORT; default is 3000. Preview is local and serves installed dist/, not an arbitrary builder output argument. Do not terminate an unknown process or expose the preview as a production service to make a test pass. The optional editor uses a different process and port.
Search misses and stale results
| Symptom | Check |
|---|---|
| No palette/index | Script and JSON responses |
| Heading absent | Actual H2-H4 with rendered ID |
| Code not found | Code intentionally stripped |
| Diagram term absent | Add equivalent prose |
| Old result | Built/deployed index and browser load |
| Wrong target | Real route, fragment and rename |
The page entry contains introductory prose before the first indexed heading. Section entries contain prose to the next H2-H4. H1/H5/H6 do not become section entries. Search is not arbitrary source grep or an authorization boundary. Inspect the actual JSON entry and browser result; a raw term match alone does not prove useful ranking/navigation.
Record index bytes and first-load/query time on actual devices for a large tree. Do not treat the earlier small benchmark as a scale guarantee. Search and navigation covers controls, matching and browser state.
Diagram and extension issues
| Symptom | Check |
|---|---|
| Mermaid remains text | Local library, fence and browser |
| Diagram render error | Syntax and console, minimal fixture |
| Bad theme contrast | Actual SVG after theme change |
| Diagram too wide | Smaller structure plus prose |
| Preview lacks task/footnote | Final reader plugin difference |
| Alert is ordinary quote | Supported marker and placement |
Build creates a Mermaid container; the browser creates SVG. Wait for actual SVG and inspect it rather than accepting container presence. Keep equivalent prose; no built-in zoom/fullscreen is supplied. Do not enable raw HTML to fix a Mermaid, footnote or task-list preview mismatch.
Use Markdown lab to compare actual source/rendered output. Inspect both themes, longest tables/code and phone widths. Fix content structure rather than shrinking normal text or changing the pinned engine merely to fit one table.
Parser/helper diagnostics
Unsupported-language errors name the encountered label:
Unsupported frontmatter language "NAME". Only YAML frontmatter is allowed.
NAME is the source label, not a literal required heading. Convert metadata to YAML without executing it. The frontmatter helper also has parseFrontmatter expects a string for non-string/non-Buffer callers and Writing frontmatter is not supported here. for attempts to use its YAML stringify engine. Those are library/maintainer contracts, not proof normal Markdown writing is unsupported. The Admin section form uses its own safe update helper.
The local preview emits MARKSTACK_PREVIEW_PORT must be 1-65535 for invalid port. It sends plain-text Invalid path 400 for failed decoding, Forbidden 403 for traversal/NUL/backslash or escaping symlink, and Method not allowed 405 with GET/HEAD Allow header. A missing file normally serves the generated 404 HTML with 404, or plain Not found when that file cannot be read. This preview contract is distinct from editor API JSON.
Verify the repair
Rebuild to a safe output, recheck affected routes/anchors and inspect actual browser content. Then check home, a deep page, missing route, assets, search, code copy and diagrams on the deployment. No builder success line validates DNS, TLS, redirect application, privacy or accessibility by itself.