# Complete setup

This walkthrough takes a fresh V2 checkout to a working documentation reader and then explains the two separate publishing choices: upload a static reader, or add a private editor for writers. Finish the local reader first. That gives you a known-good build before introducing accounts, DNS or a hosting service.

The example project is Field Guide, a fictional documentation site. Its first page helps a new team member check a development machine. Use synthetic content while learning; do not start by uploading internal documents to an unprotected public host.

# Choose what you are setting up

The preview and editor are separate servers. You do not need either running for an already deployed static reader to serve its files. You do need Node on a build/editor machine, but not on each reader’s computer.

Editor sign-in protects writing, not reading. A confidential page needs reader-host access control. A hidden section, obscure URL or private source repository does not protect generated files on a public host.

# 1. Check prerequisites and a safe workspace

The package does not set a separate minimum npm or Git version. Use compatible supported tools with the committed lockfile, then verify installation/tests rather than inventing a version guarantee. Install Node.js 24 or newer, npm and Git. The platform guide covers shell differences. Run these checks in the terminal you will actually use:

node --version
npm --version
git --version

Node must print v24 or a newer version satisfying the project’s requirement. If it prints an older version, fix that before installing dependencies. A working graphical Node installation does not prove a service or another terminal uses the same executable.

Choose a new folder where you have write access. Do not run the setup over an existing site, use a production web root, or run npm as root just to avoid permissions errors. Keep an existing site’s content, configuration, media and private data backed up before any migration.

# 2. Obtain V2 and install its locked dependencies

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

Git creates a checkout; npm ci installs the versions selected by package-lock.json. Clone access depends on whether the repository is public or your account has access. Use your normal Git authentication on your machine. Do not paste a password or token into a clone URL or a document.

For a reproducible installation, record git rev-parse HEAD. This handbook uses the pinned engine revision in the checkout command below. A new clone follows the current branch, which may be newer. If you deliberately want this exact documented engine, select that commit before installing:

git checkout 27a9763a7f1266a7495b825d818124862ae58255
npm ci

A detached HEAD is normal for a pinned checkout. Before committing local documentation changes, create a working branch with an unused name:

git switch -c field-guide-docs

If that branch already exists, inspect it rather than forcing a reset. The command creates a local branch; it does not push or open a pull request. Do not assume the package’s 1.1.4 string identifies the engine revision; record the commit too.

# 3. Build the included documentation first

npm test
npm run build
npm run serve

Tests should exit successfully. The builder prints generated routes and a completion message. Preview prints a loopback URL, normally http://127.0.0.1:3000, and stays running until Ctrl+C. Open that URL in a browser on the same machine.

Check the home page, one deep page, search, a code-copy button and theme switching. Inspect a diagram page too. This baseline proves that dependencies, generator and browser assets work before you change content. Do not use file://: search data and root-relative resources need an HTTP-served site.

If port 3000 is occupied, use MARKSTACK_PREVIEW_PORT=3100 npm run serve in a Unix shell. In PowerShell, set $env:MARKSTACK_PREVIEW_PORT = '3100' before npm.cmd run serve. Changing a preview port does not change the optional editor’s port.

# 4. Write the first Field Guide pages

Follow First site for complete _index.md and hello.md examples. Add a guides folder rather than deleting the included documentation during the first exercise. A section landing page explains what the folder contains; a normal Markdown file becomes a page.

Edit siteconfig.json carefully to give the site and header the name Field Guide. Keep valid JSON. Change the home Markdown in content/_index.md, not generated dist/index.html. Put your own local images under static/images/.

Rebuild after each content/configuration change. Open /guides/hello/, verify the title and heading anchors, then search for its heading. Titles affect URLs. Keep them stable once you have published links, or plan redirects at your host.

# 5. Pick your writing loop

For file-based writing, keep npm run watch in one terminal and npm run serve in another. Watch rebuilds supported content, template and static changes; refresh the browser after a build. Do not count on watch to detect every external configuration/data change: run an explicit build after configuration changes and inspect the result.

For browser writing, stop at a known-good reader and follow Administrator and editor. Create the first administrator with the hidden password prompt, then start the editor. Save writes source; administrator Publish Changes builds saved source. Neither automatically uploads files to a remote hosting service.

# 6. Review the exact upload

The public upload is the contents of dist/, with index.html at its root. It is not the project checkout. Check:

• Home and deep routes open through HTTP.
• CSS, JavaScript, fonts, images and search data load.
• Search results and internal links lead to the intended pages/headings.
• No confidential page, private runtime file or editor endpoint is included.
• The output directory contains the version you just reviewed, not an older build.

Never upload users.json, private runtime data, editor server code, backups or node_modules. Anything you copy into static/ is a candidate for public output, so treat that directory as publishable material.

# 7. Deploy the reader, separately from the editor

Choose static deployment for the general model or Cloudflare setup for a rendered-site workflow. Use DNS setup when adding a domain. A service/provider’s preview URL is enough for an initial deployment; a custom domain is a separate step.

After deployment, check the actual live home, a deep route, search, media, theme, missing-page response and any old redirects. A successful Git push is not proof of a successful deployment. Keep the previous reader version until these checks pass.

A team editor is a different deployment: private Node process, private writable data, service account and HTTPS proxy. Use the private editor guide. Do not enable it on this public showcase or mistake a static host for a Node server.

# Completion and test limits

You are finished when another reader can open the intended URL, follow the first guide, search it and see the expected content without needing your source checkout. Writers should also know where source lives, how to rebuild, who publishes and how to restore the previous version.

The pinned engine’s Linux install/test/build, synthetic content and local reader/editor checks were exercised. Windows/macOS commands and remote hosting/service examples are instructions or templates, not claims of having run those environments. Their pages identify the checks needed on your own installation.