Capabilities and limits
MarkStack V2 builds a static Markdown reader and includes an optional authenticated writing server. The product name V2 does not mean package version 2.0: this pin reports 1.1.4. Evaluate the required guarantees separately from the appearance of a documentation site.
Reader and content
| Capability | Boundary |
|---|---|
| Markdown pages | YAML frontmatter; title routes |
| Folder navigation | Ordered folders; title-sorted files |
| Heading search | Browser page/H2-H4 index |
| Heading rail | H2, when at least two |
| Code color/copy | Not command execution |
| Diagrams | Local lazy Mermaid rendering |
| Footnotes/tasks/alerts | Built reader extensions |
| Themes/mobile drawer | Browser UI, not device certification |
| Static hosting | Host/TLS/cache supplied separately |
Content is files, not a database-backed content CMS. There is no MDX application runtime, built-in math dialect or general plugin compatibility guarantee. Raw HTML is off by default and requires explicit owner file policy; enabling it is not HTML sanitization. Editor preview does not contain every final-reader plugin. Markdown lab shows actual renderings and checks.
Routes use ASCII title slugs, not stable file IDs. Changing a title or ancestor folder title can break old URLs. Native non-Latin/RTL routing is not guaranteed; test actual output and collisions. The builder does not check every authored link or create automatic redirects. Frontmatter and Validation limits explain risks.
Search is not a remote service, semantic search, a reader-account permission filter or a whole-source grep. Code and diagram source are stripped from indexed prose. Index scale costs browser download/preparation/memory; measure your own content. A green build does not certify relevant search results.
Optional writing server
| Built in | Not supplied by it |
|---|---|
| Local password login | SSO, MFA, identity provider |
| Admin/editor roles | Per-page custom role model |
| Assigned top-level sections | Private public-reader accounts |
| Source file actions | Binary uploader |
| Browser draft recovery | Server history or merge |
| Account and session controls | Durable session clustering |
| Safe presentation overrides | Engine/policy configuration UI |
| Staged local Publish | Git or remote deploy |
A section is a real top-level content folder, not an arbitrary navigation category. Admins manage global content/settings and publication; editors write within assignments. Root Markdown and section-root structural changes are administrator responsibilities. Hidden folders are still built/indexed, so hiding is not privacy.
Ordinary Markdown Save has no revision-token conflict check. Browser drafts are local and not a backup. Settings/section metadata have narrower revision checks, while header links replace a whole list. Coordinate writers rather than promising real-time coauthoring or conflict-free editing.
Publish builds and switches local output. It does not provision DNS/TLS, send files to Cloudflare, commit to Git or prove the remote site changed. Two switch renames are not crash-atomic. A previous output copy is not your source/account backup. Save, publish and deploy separates the steps.
Hosting and organization responsibilities
| Need | Operator work |
|---|---|
| Public distribution | Static host/CDN and domain |
| Private readers | Host or network identity controls |
| Private writer access | Private access and TLS |
| Process availability | One supervised writer process |
| Source history | Git, review and backups |
| Recovery | Source, runtime and service rehearsal |
| Event retention | Local rotation plus retention policy |
| Capacity | Measure build, search and editor |
| Compliance | Requirement review and external controls |
Account-store transactions use a lock, reload and replacement, but that is not a general multi-process editor HA design. Sessions, rate-limit counters and current publish job are in memory. A second writer process can introduce coordination problems that the static reader pattern does not solve. No clustering, distributed job queue or availability SLA is claimed.
Local operational history is bounded and can fail to write. It is not tamper-evident, immutable or a compliance archive. Restore drills must include private user/runtime files, permissions and service/proxy settings, not only HTML. Do not ship runtime data with public reader output.
Network and offline boundaries
Stock reader/editor libraries and fonts are bundled locally. That does not mean all operations are offline: fresh dependency installation, authored remote images/links and server-side favicon fetching are separate network activity. A link destination is not vetted merely because it appears in the header.
There is no bundled Node/dependency installer or general offline-install package. Prepare the required runtime and locked dependencies through your organization’s approved process. Cached browser state is not an offline-reader guarantee. Security and privacy covers outbound resources and deployment choices.
Choose by requirements
Files/Git plus static hosting suit a reviewed handbook that does not need browser writers. Add the optional editor only when authenticated server-side authoring is useful and you can operate its private process and backups. External controls can add identity, review or delivery rules, but describe them as your workflow rather than built-in MarkStack features.
If your requirement depends on native multilingual routes, server page history, SSO/MFA, concurrent merge, per-reader permissions, clustered writers or certified retention, validate a separate solution before committing. A clean interface or long handbook is not proof those guarantees exist.