Configuration

Configuration

Everything is configured in .md.ini at the project root — the directory that contains public/. The file is created on the first request; missing keys get safe defaults on every load, so an upgrade never needs a hand-edited file. Hand-added comments and key order are preserved; keys added by a new version are appended under a ; ── Keys added automatically by MD.Scribe <version> ── banner.

ADMIN_PASSWORD is one-shot: it is hashed into ADMIN_PASSWORD_HASH on the next request and the plaintext key is cleared. API_KEY (mdv_ + 40 hex characters) is generated on first load.

Two switches gate everything destructive and both default to off: ALLOW_UPDATE (apply a release) and ALLOW_RESTORE (restore content or application files).

All keys and defaults

This table is generated from config/defaults.php, so the defaults are the ones the code actually uses.

General

Key	Type	Default	Meaning
SITE_NAME	string	MD.Scribe	Shown in the header, <title> and feeds.
HOME_DOC	string	index.md	Markdown file (relative to BROWSE_DIR) rendered at the site root. Falls back to the file browser when missing.
BROWSE_DIR	string	(empty)	Where documents live. Empty = the bundled content/ directory. Accepts an absolute path, a DOCUMENT_ROOT-relative path, or a path relative to the project root.

Features (Markdown extensions)

Key	Type	Default	Meaning
AUTO_TOC	bool	true	Auto-generate a linked table of contents from document headings.
AUTO_NUMBERING	bool	true	Number headings automatically (1, 1.1, 1.2 …) unless the document numbers them manually.
AUTO_FOOTNOTES_LINKS	bool	true	Add return links from footnote definitions back to their references.
SPLIT_TITLE_BY_COLON	bool	true	Render "Topic: Subtitle" as a title plus an eyebrow line.
PARAGRAPH_BREAK_STYLE	string	double-br	double-br = single newlines become ; paragraph = classic Markdown spacing.
DOUBLE_LINE_BREAKS	bool	true	Treat a single newline inside a paragraph as a (legacy MD.Viewer behaviour).
FEATURE_IMAGES	bool	true	Render images with lazy loading, captions and lightbox zoom.
FEATURE_REF_LINKS	bool	true	Support [text][ref] links with [ref]: url definitions.
FEATURE_TASK_LISTS	bool	true	Render - [ ] / - [x] items as checkboxes (GitHub style).
FEATURE_FOOTNOTES	bool	true	Support [^1] references and [^1]: definitions.
FEATURE_SUBSUP	bool	true	Render ^superscript^ and subscript inline patterns.
FEATURE_EMOJI	bool	true	Convert :shortcode: names (1900+ GitHub gemoji aliases) to unicode emoji.
FEATURE_WIKILINKS	bool	true	Render Page, Page and Page#Heading as links to documents in the library.
FEATURE_HIGHLIGHT_MARK	bool	true	Render ==highlighted text== as .
FEATURE_MATH	bool	true	Render $inline$ and $$block$$ LaTeX math with locally-served KaTeX.
FEATURE_MERMAID	bool	true	Render ```mermaid fenced blocks as diagrams (locally-served Mermaid, with auto-repair).
FEATURE_ALERTS	bool	true	Render > [!NOTE] / [!TIP] / [!IMPORTANT] / [!WARNING] / [!CAUTION] blockquotes as callouts.
FEATURE_DEFINITION_LISTS	bool	true	Support Term / : definition blocks (PHP-Markdown style).
FEATURE_ATTRIBUTES	bool	true	Support {#id .class key=value} attribute syntax on blocks and images.
FEATURE_SMART_PUNCT	bool	false	Convert quotes to curly quotes, -- to en dash, ... to ellipsis.
GLOSSARY_TOOLTIPS	bool	true	Turn a "| Term | Definition |" glossary table into hover tooltips across the document.
UNIVERSAL_PATTERNS	bool	true	Legacy MD.Viewer inline formatting extras (kept for compatibility).

Interface

Key	Type	Default	Meaning
FEATURE_DOWNLOAD_ICON	bool	true	Per-row download control in the file browser.
FEATURE_DOWNLOAD_BUTTON	bool	true	Download the source .md from the document toolbar.
FEATURE_COPY_BUTTON	bool	true	Copy the document source .md to the clipboard from the toolbar.
FEATURE_SEARCH	bool	true	Full-text search over all documents (server-side index, no database).
FEATURE_COMMAND_PALETTE	bool	true	Quick-jump palette: files, headings, actions, themes.
FEATURE_LIGHTBOX	bool	true	Click-to-zoom overlay for document images.
FEATURE_READING_PROGRESS	bool	true	Thin progress indicator under the header while scrolling.
PWA_ENABLED	bool	true	Serve a web manifest and a service worker so the viewer can open previously read documents offline.

Content and uploads

Key	Type	Default	Meaning
DISABLE_UPLOAD	bool	true	Hides and server-blocks the "Upload .md" control in the file browser. Per-directory .md.ini may override.
DISABLE_CLIPBOARD	bool	false	Hides and server-blocks the clipboard preview in the file browser.
DISABLE_SAVE_CLIPBOARD_TO_FILE	bool	true	Hides and server-blocks saving pasted clipboard content as a new .md file.
REVISIONS_ENABLED	bool	true	Store the newest REVISIONS_MAX versions of every document on save, under storage/revisions.
REVISIONS_MAX	int	20	Newest N versions are kept; older ones are pruned on save. Allowed range 1–200.
BACKLINKS_ENABLED	bool	true	Build the wikilink backlink index and show "Linked from" under every document.
TAGS_ENABLED	bool	true	Build the frontmatter tag index and expose the public tags page.
MAX_UPLOAD_MB	int	8	Hard cap for reader uploads and admin uploads (also capped by PHP upload_max_filesize).

Security

Key	Type	Default	Meaning
ADMIN_ENABLED	bool	true	Master switch for /admin (dashboard, file manager, backups, updater…). Set false to serve docs only.
ADMIN_USERNAME	string	admin	Login name for the admin panel.
ADMIN_PASSWORD	string	(empty)	Set a plaintext password here once; MD.Scribe hashes it into ADMIN_PASSWORD_HASH on next load and clears this key.
ADMIN_PASSWORD_HASH	string	(empty)	password_hash() output. Managed by the admin panel — do not edit by hand.
ADMIN_RATE_LIMIT	int	10	Failed admin logins allowed per IP per 15 minutes before temporary lockout.
API_KEY	string	(empty)	Credential for the JSON machine API (status/conflicts/install). Generated on first run.
ALLOW_UPDATE	bool	false	Enables checking and applying updates from GitHub (admin panel + updater shim).
ALLOW_RESTORE	bool	false	Enables listing and restoring backups.
ALLOW_CREATE_INDEX_PHP_LINK	bool	true	Enables creating/removing the root index.php shortcut from the admin panel.
ALLOW_RAW_HTML	bool	false	Keep sanitized author HTML (allowlisted tags/attributes). When false, raw HTML is escaped/stripped. Output is always sanitized.
ALLOW_IFRAMES	bool	false	Permit <iframe>, , and in documents (only meaningful with ALLOW_RAW_HTML).
ALLOW_EXTERNAL_IMAGES	bool	true	When false, images pointing to other origins are replaced with a placeholder note.
SECURITY_HEADERS	bool	true	X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy.
SECURITY_CSP	bool	true	Strict CSP with per-request nonces for inline scripts/styles.
TRUSTED_PROXIES	string	(empty)	Comma-separated proxy IPs allowed to set X-Forwarded-For. Empty = ignore forwarded headers.

Performance

Key	Type	Default	Meaning
CACHE_ENABLED	bool	true	Cache rendered documents keyed by source hash + feature set. Invalidated automatically on file change.
CACHE_TTL	int	3600	Cache-Control max-age for rendered documents and static assets.
MAX_SCAN_DEPTH	int	8	Directory depth limit for the file browser and search index.
MAX_FILES_SCAN	int	10000	Safety cap for the recursive scanner.
SEARCH_MAX_RESULTS	int	50	Cap for the search page and palette results.

Feeds and discovery

Key	Type	Default	Meaning
SITEMAP_ENABLED	bool	true	Serve an auto-generated sitemap of all documents.
RSS_ENABLED	bool	true	Serve feed.xml with recently modified documents.

Appearance

Key	Type	Default	Meaning
THEME_DEFAULT	string	zinc	Base theme applied on first visit (before the visitor picks one). See the Themes catalog.
MODE_DEFAULT	string	system	light | dark | system — used on first visit only.
SORT_DEFAULT_KEY	string	modified	name | size | modified — initial order of the file browser table.
SORT_DEFAULT_DIR	string	desc	asc | desc.

Diagnostics

Key	Type	Default	Meaning
APP_ENV	string	production	production | development. Development shows detailed error pages.
APP_DEBUG	bool	false	Log debug-level messages and show stack traces on error pages. Never enable on a public server.
LOG_LEVEL	string	warning	debug | info | warning | error — minimum level written to storage/logs.
LOG_RETENTION_DAYS	int	14	Older daily log files are deleted automatically.

Per-directory overrides

A .md.ini inside the browse root is a per-directory override that honours only DISABLE_UPLOAD, DISABLE_CLIPBOARD and DISABLE_SAVE_CLIPBOARD_TO_FILE. The deeper file wins. Installation-level keys placed there are ignored, and the log says so: [MD.Scribe] ignored installation-level key ALLOW_UPDATE in directory ini ….

PHP settings

deploy/php.ini is the recommended production posture: display_errors = Off, session.cookie_httponly = 1, opcache.enable = 1, opcache.validate_timestamps = 0. With validate_timestamps = 0 a code change is invisible until PHP-FPM is reloaded — that is the usual cause of "the fix did nothing" after an update.

Environment

Key	Values	Effect
APP_ENV	production, development	Selects the error verbosity default.
APP_DEBUG	bool	Stack traces in the log. Never enable on a public host.
LOG_LEVEL	debug, info, warning, error	Log threshold.
LOG_RETENTION_DAYS	int	How long storage/logs/app-*.log is kept.

Security posture

• SECURITY_HEADERS and SECURITY_CSP are on by default; the CSP is default-src 'self' with a per-response nonce for the few inline scripts the UI needs.
• ALLOW_RAW_HTML and ALLOW_IFRAMES are off by default; raw HTML is always sanitised through a DOM allowlist, never rendered as-is from the file.
• TRUSTED_PROXIES lists the proxy addresses whose X-Forwarded-* headers are believed — needed for a correct client IP behind a reverse proxy (rate limiting depends on it).
• ALLOW_EXTERNAL_IMAGES is on by default: remote images load, and they are the only third-party content a page can pull.