MarkdownManager v0.956

MarkdownManager is a fast, flat-file Markdown editor you can host yourself. No database. No lock-in. Just a clean web UI for plain text notes that live as .md files on disk.

Use it as a simple notebook, or flip on Website Publication Mode (WPM) to run a lightweight CMS workflow with publish states, metadata, and HTML export.

Recent updates:

• v0.956: WPM synchronization now reconciles reviewed Markdown and managed Jinja templates safely before rendering, with reusable minipc/Jinja sync timers. The visual editor has translated tooltips, clearer active formatting controls, optional superuser-managed PNG/SVG branding, improved preview fidelity for headings, checkmarks and download assets, and a Dutch normal-user workflow guide.
• v0.953: WPM now supports a conflict-aware, instance-configured publication runner with five-minute status reporting, safe static/image synchronization, and a reusable onboarding path. Authors can submit work for processing, superusers see pending work first, and new WPM pages use the same configured metadata defaults as Article metadata, including today's post date.
• v0.952: WPM preview now preserves supported Jinja macro source during visual editing, renders common site macros such as special.bigheader, prevents duplicate page pictures, and aligns blog metadata headers with the source template order. The Markdown pane now supports localized find (Ctrl+Shift+F) and confirmed find/replace (Ctrl+Shift+H).
• v0.951: WPM now applies trailing image classes directly to images, preserves responsive Tailwind class syntax in fenced divs and attribute lists, and prevents duplicate legacy bullet rendering in blockquotes.
• v0.95: WPM visual preview and reusable sections/macros are more reliable, custom format sources are configurable, legacy Jinja syntax stays out of visual editing, and nested instances can use relative assets, local fonts, shared authentication, resilient image lists, and isolated preview CSS without affecting the editor UI.
• v0.93: WPM folder sorting now keeps newest articles first by post_date, then creationdate, then filename date; date parsing handles Dutch/English display dates; hide-Markdown image tips are suppressed; article metadata now shows the slug in the title and includes an inline page_picture image picker.
• v0.92: WPM public-link cleanup, visual link editing, section snippet/include support, friendlier article metadata editing, id attribute-list support, safer inline JSON bootstrapping, cache-busted static assets, auth setup refresh, and EN/NL translation updates.
• v0.91: TOC stability fixes for WPM/visual preview, including a locked non-editable TOC shell, correct two-column right-TOC layout, restored sticky behavior inside the editor preview, and a regression test that guards the layout/CSS contract.
• v0.9: WPM hide-markdown/visual editing mode, source toggle, article metadata modal, optional TOC toolbar control, responsive toolbar fixes, WPM copy cleanup, localized EN/NL UI strings, and test-login/config updates.
• v0.81: major Explorer/index overhaul with lazy-loaded + cached note trees, sticky and unified explorer controls, keyboard/focus and SPA navigation fixes, smarter focused-file rename behavior, split-view layout controls, and broader UI/settings polish.
• v0.8: optional AW-SSG template export plugin (Jinja), smarter WPM metafield mapping/defaults, and cleaner class/footnote template output.
• v0.7: toolbar sizing/icon polish, WPM publish badges/icons, list-item class attributes, preview/meta fixes (author defaults), and active note icon sync.
• v0.6.3: editor bracket-pair highlight, HTML-only author metadata in WPM, and drag/drop internal link insertion.
• v0.6: TOC sidebar option, wet export font links, safer auth hashes, and mobile pane focus fixes.

Why check this out

• Flat files only: your notes are readable outside the app and easy to back up.
• Instant live preview: Markdown updates on save, with clean HTML output.
• WPM mode: publish states, badges, author/subtitle rules, and metadata control.
• CMS-ready: export HTML directly or pair with AW-SSG for a structured full-site workflow.
• No build chain: drop it on a PHP host and go.
• Writing-first UX: open, edit, and publish without leaving your notes.

Short comparison: Jekyll, Astro, and other SSGs

• Jekyll: great for static sites and GitHub Pages, but no live editor or content workflow. MarkdownManager is the authoring UI.
• Astro: powerful for component-driven sites, but requires a build pipeline. MarkdownManager is light and runs anywhere PHP runs.
• Hugo / Eleventy / Next.js: fast and flexible, but still build-focused. MarkdownManager stays in edit mode and can export to them.
• AW-SSG: use MarkdownManager to edit and export wet HTML, then let AW-SSG handle structure, navigation, and the final static site.

Quick start (local)

1. Clone this repo.
2. Copy .env.example to .env.
3. Optional: remove example-notes/ once you are comfortable.
4. Run a local PHP server:

php -S localhost:1234

Open http://localhost:1234/index.php in your browser.

Everyday use

• Click +MD to create a note.
• Use the left explorer to filter and open notes.
• Save and preview in the editor.
• Copy or export HTML when needed.

Use it as a CMS

MarkdownManager can act as a lightweight CMS in two ways:

1. Export to HTML
   Use the built-in HTML copy/download tools for clean output.

2. Pair with AW-SSG
   Write content in MarkdownManager, then let AW-SSG build a full static site. This gives you a proper CMS pipeline without leaving Markdown.

Enable Website Publication Mode (WPM) in Settings to unlock publish states, metadata, and workflow rules.

Features at a glance

• Live Markdown editor with HTML preview.
• HTML export: dry, medium, and wet modes.
• Theme overrides + custom CSS stored in settings.
• Image manager with upload and insert.
• Link modal with internal/external/footnote helpers.
• Multi-language UI (EN/NL/DE/FR/PT/ES/IT).
• Works on desktop and mobile.

Languages

The UI can be switched between English, Dutch, German, French, Portuguese, Spanish, and Italian when the matching translation files are present. Version 0.956 retains those language-specific UI labels while adding clearer visual-editor formatting feedback and a Dutch guide for normal WPM users at docs/GEBRUIKERSHANDLEIDING_NL.md. Version 0.952 added localized find/replace actions, match feedback, and replacement confirmations.

Security warning (read this)

MarkdownManager is not safe to expose to the public internet. It has no accounts, no MFA, no rate limiting, and only lightweight protection for "secret" notes. WPM mode adds workflow safeguards, but it does not make the app safe for public exposure. Run it on localhost or a trusted private network only.

Configuration

Edit .env to tune paths and features:

• PLUGINS_DIR, STATIC_DIR, IMAGES_DIR, THEMES_DIR, TRANSLATIONS_DIR
• METADATA_CONFIG_FILE, METADATA_PUBLISHER_CONFIG_FILE
• WPM_BASE_URL (for public link + search plugin)
• SECRET_MDS_FILE, SECRET_MDS_PASSWORD

Export-related settings use the MDM_ prefix (short for MarkdownManager).

Website publication mode (WPM)

WPM is built for teams or individuals who want a publishing workflow:

• Requires metadata at the top of each note.
• Adds publish states: Concept, Processing, Published.
• Shows state badges in the explorer.
• Enforces author/subtitle rules (configurable).

Example metadata block:

{page_title: Example page title}
{page_subtitle: Optional subtitle}
{post_date: 2025-11-23}
{published_date: 2025-11-30}
{publishstate: Published}
{author: Jane Doe}

Notes:

• {key: value} is the canonical metadata format.
• WPM explorer sorting uses post_date, then creationdate, then the filename date.
• WPM settings are stored in metadata_config.json.

HTML export modes

• Dry: clean HTML, no classes or styles.
• Medium: class names only.
• Wet: includes CSS (theme + custom overrides).

Semidry/Wet exports only keep classes that you explicitly add via {: class="..."} in Markdown.

Plugins

MarkdownManager ships with a small plugin system. Plugins live in plugins/ and are auto-loaded. Most plugins add explorer sections or header widgets, but they can also provide automation tooling.

GitHub Pages export plugin (github_pages_export)

This plugin is a build-time integration that turns your MarkdownManager notes into a static site and deploys it to GitHub Pages. There is no "auth plugin" needed. GitHub Actions already provides GITHUB_TOKEN when the workflow runs, and the deployment step uses the Pages OIDC permissions. Plugin file: plugins/github_pages_export_plugin.php.

Tutorials

Playful step-by-step guides live in example-notes/tutorials/:

• example-notes/tutorials/github_pages_tutorial_en.md
• example-notes/tutorials/github_pages_tutorial_nl.md
• example-notes/tutorials/github_pages_tutorial_de.md
• example-notes/tutorials/github_pages_tutorial_fr.md
• example-notes/tutorials/github_pages_tutorial_es.md
• example-notes/tutorials/github_pages_tutorial_it.md
• example-notes/tutorials/github_pages_tutorial_pt.md

Think of it as: write notes -> push -> GitHub Pages does the rest. No manual HTML dumps, just a clean deploy that updates itself when you push.

If you want the full step-by-step (with screenshots-style clarity), open one of the tutorials above. They are short, friendly, and actually fun to follow.

Google site search plugin (google_search)

WPM-only plugin that adds a site-scoped Google search box for your public domain (WPM_BASE_URL).

Extras

• links.csv: shows a "Shortcuts" list (CSV with shortcut,url).

Troubleshooting

• "Cannot create/delete/save": fix filesystem permissions for the PHP/webserver user.
• "Secret note is locked": open the file in index.php first and enter the password.
• Filenames rejected: only A-Za-z0-9._- and unicode letters/numbers are allowed; must end in .md.
• Math not rendering: MathJax is loaded from a CDN; offline networks will block it unless you host it locally.

Changelog (short)

See CHANGELOG.md for full details.

• 0.956: safer WPM Markdown/template reconciliation and renderer sync templates, translated visual-editor toolbar tooltips and clearer toolbar states, superuser-managed PNG/SVG branding, improved preview fidelity for headings/checkmarks/download assets, hidden-note keyboard navigation, and a Dutch normal-user guide.
• 0.951: WPM image classes now apply directly to images, responsive Tailwind class syntax is preserved in fenced divs and attribute lists, and repeated quote attributes no longer create duplicate legacy bullets.
• 0.95: WPM visual preview resolves supported Jinja macros and reusable sections while hiding unresolved legacy syntax; custom format sources are configurable; nested instances support relative asset paths, local fonts, optional shared authentication, reliable image JSON, preserved inline style URLs, and preview CSS that cannot reposition editor dialogs.
• 0.93: WPM explorer date sorting now uses post_date before creationdate/filename fallback and keeps newest articles first, publish-state grouping no longer overrides default date sort, Dutch/English display dates parse correctly, the image insertion tip is hidden in hide-Markdown mode, and Article metadata now shows slug in the title with an inline page_picture image picker.
• 0.92: WPM public links now generate clean trailing-slash URLs and update with publish state, visual links can be edited through the link modal, section snippets/includes are available for reusable content, article metadata editing is friendlier, attribute lists support id, script JSON/static assets are safer to load, explorer caches were bumped, auth setup refreshes status, and EN/NL labels were updated.
• 0.91: TOC stability fixes for WPM/visual preview, including correct right-column layout anchoring, sticky editor behavior, non-editable TOC chrome, and a regression test for the TOC grid/CSS contract.
• 0.9: WPM visual editing mode with hide-markdown layout, source toggle, article metadata modal, optional TOC toolbar button, responsive toolbar cleanup, localized EN/NL labels, and safer WPM settings copy.
• 0.81: Explorer/index got lazy-loading + caching, sticky and unified explorer controls, improved keyboard/focus flow and SPA loading, focused-file rename upgrades (including optional date-prefix keep in non-WPM), split-view layout controls, and broader settings/UI cleanup.
• 0.6.2: JS refactor into mdm.* modules with shared helpers and core bootstrap.
• 0.6: TOC sidebar option, wet export font links, safer auth hashes, and mobile pane focus fixes.
• 0.5.1: Foldered export index, Mermaid in exports, optional repo footer, and Pages workflow polish.
• 0.5: GitHub Pages export plugin + CLI wet HTML exporter, settings checks, UI upgrades.
• 0.4.3: Custom CSS inserts, HTML tab expansion, repeat format shortcut, heading previews.
• 0.4.2: Spanish/Italian UI, refreshed tutorials, new ES/IT tutorial notes.
• 0.4.1: WPM state sync, metadata date options, export cleanup, toolbar overhaul.
• 0.4: Explorer drag/drop + folder rename, example notes move, image manager improvements.
• 0.3.3: Security hardening, {TOC}, HTML preview upgrades, WPM folder rules.
• 0.3.2: WPM Google site search + public header link, translated UI strings.
• 0.3.1.2: Settings cleanup, copy workflow upgrades, HTML preview polish, import/export.
• 0.3.1: More translations + tutorials, HTML preview improvements, AJAX save + replace.
• 0.3: WPM mode, sorting options, settings tweaks, mobile layout polish.
• 0.2: Plugins, image manager, HTML export, folder UX improvements.
• 0.1.0: Initial public release.