Hosting and maintenance

This folder is a self-contained Node.js documentation site. Markdown files are the canonical content. The server renders HTML, serves screenshots, and offers plain Markdown and JSON entry points for AI agents.

Run locally

Requirements: Node.js 22 or newer and npm.

cd C:\git_repos\scishield\documentation
npm ci
npm start

Open http://127.0.0.1:4173. The application itself does not need to be running to read these guides and screenshots.

On macOS/Linux, change into the equivalent checkout's documentation folder and use the same npm commands. The server resolves files relative to its own location, independently of the launch directory.

Configure host and port

The default listener is 127.0.0.1:4173. Set HOST and PORT to change it.

$env:HOST = '127.0.0.1'
$env:PORT = '4180'
npm start

HOST=127.0.0.1 PORT=4180 npm start

The site is read-only and has no application login. It does not reuse the SciShield session or query live application data. Its screenshots include the captured dataset; use your webserver's authentication/access controls when hosting them for a restricted audience.

Host behind a webserver

Copy the folder to a server with Node.js, run npm ci --omit=dev, and run node server.mjs under your preferred service manager. Keep the Node listener on loopback when a reverse proxy runs on the same machine.

Example nginx location inside your existing HTTPS server block:

location / {
    proxy_pass http://127.0.0.1:4173;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
}

The site uses root-relative URLs. Host it at the root of a dedicated hostname, for example docs.example.org/. Mounting it under a subpath such as /help/ requires adapting the URL generation and asset links. Configure TLS and any required authentication at the reverse proxy.

There is no static HTML build step. A plain static file host alone will serve Markdown but will not provide this HTML renderer or search endpoints.

Routes for readers and agents

All guide and search routes work without client-side JavaScript. The small browser script only preserves the search input value. Every rendered guide has a direct View Markdown link, and its links to other guides point to HTML. The original Markdown keeps its ordinary relative .md links for repository and agent reading.

Search specification

Search trims the query, splits it on Unicode whitespace, lowercases and deduplicates the terms, and requires every term to occur in a single page's complete Markdown source. Matching is literal substring matching. Terms can appear in any order and in different sections of a page.

Conceptually, the predicate is contains(word1) AND contains(word2). It is equivalent to the requested LIKE '%word1%' AND LIKE '%word2%' behavior for ordinary terms, without SQL wildcard interpretation. Percent signs, underscores, punctuation, and quotes are literal. Search does not use a database.

Results follow the guide navigation order. Blank queries return no results. Unknown words return an explicit no-results state. Screenshot pixels and live application data are not indexed.

Update content

1. Edit an existing root-level .md file or add a new one with a single level-one title.
2. Link to another guide with a relative Markdown path, for example [Training](training.md).
3. Put screenshots under assets/screenshots and use a relative image reference, for example ![Home page](assets/screenshots/home.jpg).
4. Review the image for the intended audience and provide written steps alongside it.
5. Update Scope and verification when adding verified screens or changing limits.
6. Reload the guide. Content and search read Markdown at request time.

New .md files automatically appear in navigation, search, /api/pages, /llms.txt, and /all.md. The ordering list in server.mjs places core guides first; additional guides follow alphabetically. Screenshot files are served as local assets; no CDN or external font service is required.

capture-evidence.json is maintainer evidence from the browser exploration. It is not a guide and is not exposed by the Node server. Refresh it only when performing another documentation capture.

Verify changes

npm test

Tests cover AND search with reversed terms, case and whitespace, literal special characters, no-result queries, raw Markdown and AI indexes, HTML rendering, source links, screenshots, missing routes, request methods, path handling, sanitization, and local Markdown/image links.

The server serves only the guide routes, indexes, and approved assets. Raw HTML in Markdown is sanitized, and a Content Security Policy restricts executable assets to this origin. Dependencies are recorded in package-lock.json; use npm ci for reproducible installation.