Skip to content

MD.Scribe v3.1.0 - Aurora (PHP 8.3 Markdown docs: viewer, editor, admin panel)

Latest
Latest

Choose a tag to compare

View all tags
@paulmann paulmann released this 14 Oct 07:27
· 15 commits to main since this release
v3.1.0
70ccf62

MD.Scribe v3.1.0 — "Aurora"

Self-hosted documentation for a folder of Markdown files — with an editor, an admin panel,
full-text search and zero CDN dependencies. PHP 8.3, no database, no build step.

First release under the name MD.Scribe. Until 3.0.1 this project was published as
MD.Viewer; that repository still exists and is untouched. Same code, same contracts, new name
and new home — 3.1.0 is a rename release, not a rewrite: application behaviour is unchanged.

Install

Download MD.Scribe-3.1.0.zip below — it bundles vendor/, so Composer is not needed:

unzip MD.Scribe-3.1.0.zip -d /var/www/docs
chmod -R u+w /var/www/docs/storage
# docroot: /var/www/docs/public  (recommended) or the project root

From a clone instead:

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

Open admin.php for first-run setup; the viewer works before that. Requirements: PHP >= 8.3
with mbstring, dom, libxml, json (curl + phar + zip recommended for the updater and
backup archives).

Why the name changed

The old name described only the reading half of what v3 became. This is a viewer, an editor, an
admin panel, a publisher and a search index — "Scribe" covers the whole where "Viewer" covered one
part. The practical numbers, measured on GitHub (in:name): 750 repositories match md-viewer and
686 match mdview, against 24 for md-scribe — which was also free on npm, free as a .dev
domain and unused in this account.

What is in 3.1.0

Area Change
Naming Version::REPO / RAW_BASE / API_BASE and userAgent() point at paulmann/MD.Scribe
User-visible text Window titles, admin header and login page, <meta name="generator">, footer, X-Powered-By, default SITE_NAME, console banner, bootstrap error messages
Packages composer.json is now mdscribe/md-scribe; composer.lock content-hash recomputed and verified with composer validate --check-lock
Docs README, docs/, content/ pages, LICENSE, and the deployment samples (Docker, nginx, Caddy, php.ini)
Manifest config/manifest.json rebuilt: 921 files, app MD.Scribe, version 3.1.0

Fixed in the same release

The self-updater pinned a product name when unpacking a release archive — it looked for
glob('.../MD.Viewer-*'). An archive named after the repository (MD.Scribe-main/) would have
been rejected with "does not look like a release". It now accepts any <name>-<ref> directory
containing config/manifest.json, with a fallback for a flat archive.

.gitignore did not ignore vendor/ at all, so git add -A would have committed 723 dependency
files. Added as /vendor/; reproducibility is kept through the committed composer.lock.

Deliberately unchanged

  • The PHP namespace MdViewer\. It is an internal identifier shared by every class in src/;
    renaming it would touch every file for no user-visible gain and would break code that type-hints
    these classes.
  • Every v2 compatibility contract: md.php?file=…, &download=1, updater.php?update=?restore=,
    the machine-API envelope {ok, action, version, steps, files, conflicts, errors}, per-directory
    .md.ini layering, mdv_feat_* cookies, and the 14-layer path validator.
  • Historical references to v2 still read MD.Viewer v2 … where they describe the previous
    product (upgrade guide, changelog, compatibility notes). v2 was MD.Viewer.
  • Upgrading in place from 3.0.x works: the tracked file list and the API envelope are unchanged,
    and .md.ini keys are the same — SITE_NAME keeps whatever value the installation already has.

Verified

  • php -l across 110 PHP files outside vendor/: 0 errors; node --check on both committed
    bundles: clean.
  • Served with PHP 8.5.0: home, themes catalogue and search API answer 200 and report
    MD.Scribe 3.1.0 in <meta generator>; /admin.php answers Setup · MD.Scribe Admin;
    a missing document answers 404; updater.php?action=status&format=json answers
    {"ok":false,…,"error":"unauthorized"} without a key — the v2 contract intact.
  • The release archive was unpacked and served before publishing; Version::REPO inside it points
    at the new repository.
  • PHPUnit and PHPStan were not run on the build machine: its vendor/ is a --no-dev install,
    so neither tool is present. .github/workflows/ci.yml runs lint, PHPStan level 6 and PHPUnit on
    PHP 8.3 and 8.4 for every push.

Documentation

The wiki is being published at https://github.com/paulmann/MD.Scribe/wiki (22 pages: install
and deployment, the complete .md.ini reference, the Markdown extensions matrix, the self-updater
and machine-API guides, and the security hardening guide).

Full changelog: CHANGELOG.md

Assets 3
Loading