MarkStack

Markdown in. A searchable knowledge base out. Your files, your hosting, your workflow.

MarkStack turns folders of Markdown into a fast static documentation site. Write with your usual editor and Git, or use the included browser editor with live preview, section-based accounts and an Admin console. Readers get search, clear navigation and light or dark themes. The public host needs no database and no application server.

Designed for a potato

🥔 Runs on almost nothing. Costs almost nothing to host.

MarkStack runs on a machine with 1 vCPU and 1 GB of RAM. If it runs there, it runs anywhere. The published site is plain static files, so it can sit on a free static host or the smallest server you can rent. There is no database and no application server to pay for.

No "Enterprise tier" needing 16 cores. The enterprise tier is the same potato with a nicer logo.

The build is one Node.js process and the output is a folder of files. Readers never touch a running MarkStack application, so reader traffic does not load your server.

Privacy and security first

Editor sign-in protects editing, not reading. Publishing makes content readable to anyone who can reach the static host. For private material, use your own network or host-level authentication. Never publish passwords, recovery codes or confidential records.

"Hide from sidebar" is not privacy. Hidden sections still build, stay reachable by URL and can appear in search.

Keep the private data folder private and backed up. It holds password hashes, settings and history. Never commit it, upload it with dist/ or serve the project root.

The editor server fetches header-link icons. When an administrator adds or refreshes a header link, the server contacts that address to download its icon, so the editor host needs outbound internet access for this. Readers do not contact those sites to see the icon; only clicking the link does.

Remote images contact other sites. If a page points to an image hosted elsewhere, the reader's browser requests it from that site, which can see the reader's IP address. Keep images in static/images/ to avoid this.

Fonts and diagrams are bundled. IBM Plex, Mermaid and the other browser libraries ship with MarkStack and are served from your own host, so reader pages make no requests to Google Fonts or a CDN. A fresh install from source still downloads npm dependencies. The two cases above (header-link icons and remote images) are the exceptions. For a team editor, use HTTPS behind a reverse proxy.

At a glance

Screenshots use a synthetic "Field Guide" site, fictional accounts and example domains.

Contents

• Designed for a potato
• What is included
• Quick start
• How the pieces fit
• Writing content
• The reading site
• The browser editor
• The Admin console
• Save, publish and Git
• Security
• Hosting
• Commands
• Troubleshooting and limits
• Documentation map

What is included

Built for documentation, handbooks, runbooks and team knowledge bases. The reader is static; the writing tools are optional.

No proprietary content format. Skip the editor, keep your files in Git and build in CI, or run the editor privately for browser-based contributors. Saving never commits or pushes to Git for you.

Quick start

Install Node.js 24+ and npm, then:

git clone https://github.com/KineticEnforcer/MarkStackV2.git
cd MarkStackV2
npm ci
npm run build
npm run serve

Open the address printed by serve. Any static server can serve dist/ instead.

Optional browser editor

npm run editor:create-admin -- --user admin
npm run editor

The command asks for a password at a hidden prompt. Open http://127.0.0.1:3001 and sign in. The editor listens on this computer only by default. For a team, see the team server guide.

How the pieces fit

content/ + static/ + templates/ + siteconfig.json
                       |
                   build.js
                       |
                     dist/
                       |
            static web host -> readers

browser editor -> saved Markdown -> Publish Changes -> dist/

Edit the source, never the generated HTML. The public host needs no Node server. Publishing updates the local dist/ folder; getting it to a remote host is a separate step.

Writing content

content/
├── _index.md          Home page
├── guides/
│   ├── _index.md      Section page
│   └── quickstart.md  A normal page
└── .drafts/           Leading dot: not built

Each folder is a section and each .md file is a page. A page starts with a small YAML header:

---
title: "Setup: Linux"
description: Install and verify the tools.
updated: 2026-10-12
---

Your page content.

The page title also becomes its web address, so renaming a title can break links. If two pages end up with the same address, the build stops instead of overwriting one. See the content model, frontmatter and media and links guides.

The reading site

Dark theme and search screenshots

The browser editor

The preview is a writing aid, not an exact copy of the published page. Footnotes, task-list checkboxes and heading anchors are added by the build, not by the preview. Images can load when their URLs are reachable from the editor; remote images can contact other sites. Check the built page before publishing.

Browser drafts are a convenience, not a backup. The editor is not a live collaboration tool or a Git history viewer.

The Admin console

Administrators open it from the account menu. Editors never see it.

Admins manage users, sections, pages, site settings, header links, security status, publish history and an activity log. Accounts use usernames, not required email addresses. Details are in the users and roles and system guides.

More Admin console screenshots

Save, publish and Git

Publish includes every saved page, including other editors' changes. Unsaved tabs and drafts are left out. If a build fails, the live site stays as it was. The button does not commit, push or upload anywhere.

Publish history

Security

Not built in: HTTPS, multi-factor sign-in, single sign-on or reader login. Put the editor behind an HTTPS proxy, and use host or network authentication if readers must sign in. Full details are in the security guide.

Hosting

npm ci
npm run build
# Deliver the CONTENTS of dist/ to the static host.

For a team editor, keep the code, the built site and the private data in separate folders, run it as a low-privilege user and put HTTPS in front. See the team server guide and the hosting guide. Back up content/ and the private data folder; the built dist/ can always be rebuilt.

Commands

The build clears its output folder. Never point --out at source files or data you need. To contribute, see CONTRIBUTING.md.

Troubleshooting and limits

More in the common issues and FAQ.

Documentation map

Build the content/ folder to read the guides through MarkStack, or open the source files below.

License and author

Created by KineticEnforcer. Licensed under GPL-3.0; read the terms before redistributing or modifying. No commercial hosting service is required.