Getting Started

Getting started

1. Install

Either take the release archive (it ships vendor/, so Composer is not needed on the host):

unzip MD.Scribe-3.5.0.zip -d /var/www/docs
chown -R www-data:www-data /var/www/docs/storage

or clone and install the dependencies yourself:

git clone https://github.com/paulmann/MD.Scribe.git /var/www/docs
cd /var/www/docs
composer install --no-dev --optimize-autoloader

2. Point the document root at public/

server {
    listen 80;
    server_name docs.example.com;
    root /var/www/docs/public;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$args;
    }

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_pass unix:/run/php/php8.5-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }

    types { application/manifest+json webmanifest; }
}

docs/installation.md has Apache, Caddy and shared-hosting variants.

3. Open it

.md.ini appears at the project root on the first request, with API_KEY generated and ALLOW_UPDATE / ALLOW_RESTORE off. The bundled content/ directory is enough to see the viewer work.

4. Verify — six requests, no guessing

curl -fsS "https://docs.example.com/" -o /dev/null
curl -fsS "https://docs.example.com/index.php?page=browser" -o /dev/null
curl -fsS "https://docs.example.com/index.php?api=search&q=markdown" | grep -q '"ok":true'
curl -fsS -o /dev/null -w '%{http_code}' "https://docs.example.com/index.php?file=nope.md" | grep -q 404
curl -fsS "https://docs.example.com/manifest.webmanifest" | grep -q '"name"'
curl -fsS -o /dev/null -w '%{http_code}' "https://docs.example.com/updater.php" | grep -q 200

Expected: three bodies return 200, the search body starts with {"ok":true,…}, a missing document returns 404, the manifest is served, and the updater is reachable.

5. First admin run

Open /admin.php. Until a password exists the panel offers setup only — from localhost the new password alone is enough; remotely you also enter the one-time code from storage/logs/setup.log (mode 0600). The password must be at least 10 characters.

After login, Security & health (admin.php?action=health.run) must be green on every check.

6. Write something

Files → New from template gives you a skeleton (ADR, meeting notes, how-to, reference, blank), the editor opens it, Ctrl/⌘+S saves with conflict detection, and Backups & trash lets you take a snapshot before bulk edits.