Wikied

wikied is a local Markdown editor for project documentation. It starts from a Node CLI, serves a localhost-only Express app, and edits Markdown files under the selected workspace root.

Run

From a published package:

npx wikied
npx wikied docs

From a local tarball on Windows (run from outside the project directory to avoid npm deduplication issues):

cd $env:TEMP; npx --yes --package "C:\Projects\learning\site-editor\wikied-0.9.3.tgz" wikied "C:\path\to\your\docs"

Clone a repository before opening the editor:

wikied --git https://github.com/your-org/your-repo.git

Documents

• Project Documentation: implemented behavior, screenshots, feature set, and known gaps.
• Requirements: implemented product goals, current scope, known gaps, and acceptance criteria.
• Architecture: CLI, server, client, API, settings, path safety, and data flow.
• Technical Specification: package layout, REST API, revision model, Markdown support, and test strategy.
• Design: current UI layout, editor modes, file tree behavior, screenshots, and accessibility notes.
• How To Run Wikied: user-facing CLI and browser workflow.
• How To Develop: contributor setup and development commands.
• How To Package And Run Locally: clean local build, npm pack, and tarball execution.
• How To Test: unit, client, server, e2e, lint, and screenshot checks.
• How To Release: pre-release validation and publish checklist.
• Changelog: release notes and notable user-facing changes.

Current Feature Set

CLI and Server

• CLI startup through wikied, npx --package <tarball> wikied, or node dist/cli/index.js.
• Optional root path argument; defaults to the current directory.
• --git <url> flag clones a repository into an empty directory before starting the server.
• Localhost-only Express server bound to 127.0.0.1.
• Bundled React app served from dist/client.

Layout

• Mantine AppShell layout: 48 px header, left file-tree navbar (260 px, collapsible), conditionally rendered right aside (300 px), full-width editor canvas, 24 px sticky status bar.
• Left file-tree panel toggled by a hamburger icon; open/closed state persisted to localStorage.
• Right aside panel persists its open/closed and pinned-panel state to localStorage.

Theming

• 4 accent color themes: Blue (default), Red, Purple, and Slate — selectable as color swatches in the Settings popover. Choice persists to localStorage.
• Color scheme: System / Light / Dark segmented control in Settings. Mantine applies preference immediately.
• Left navbar background is tinted with the active accent color (shade 0), with an accent-colored border separating the navbar header from the file tree (shade 2).
• Status bar, loading screen, and header brand mark all adapt to the active accent.

File Tree

• Recursive file tree in the left navbar; Markdown files are enabled, non-Markdown files shown dimmed.
• Expand and collapse directories; active file highlighted.
• Orange filename and save icon on dirty (unsaved) files.
• New Markdown file button on directory hover.
• Rename action on the active file row.

File Navigation

• Center filename pill in the header shows the active basename; click or press Ctrl+P to open an inline file picker.
• Picker shows the full folder tree when empty; collapses to a flat filtered list while typing.
• Orange dot beside the pill indicates the active file has unsaved changes.

Editor Modes

• Rich mode (default): MDXEditor with toolbar for headings, emphasis, lists, links, images, tables, frontmatter, admonitions, and code blocks.
• Preview mode: GitHub-flavored Markdown rendering with Mermaid diagram support. Built-in style presets: Default, GitHub, Docs, Print, and Minimal.
• Toggle between modes via a floating pill button at the top-right of the editor canvas; the style selector opens from a chevron on the same pill.

Diagrams

• Diagram Builder (src/dex): a self-contained visual diagram editor with live Mermaid preview. Supports five types:
  • Sequence — form-driven builder with participants, messages (all 8 arrow types), activation bars, loop/alt/opt/par blocks, notes, and autonumbering.
  • Flowchart, ER, Class, Timeline — split-pane code editor with live preview.
• Diagram files: .md files with a <!--dex:type--> header are routed to the correct builder on open. Create them via File tree → New diagram or the New file modal Diagram tab.
• Insert diagram: Rich editor toolbar Diagram ▾ dropdown — pick a type to open the builder with a starter template; inserts a ```mermaid``` block at the cursor on confirm.
• Edit existing diagram: hover a rendered diagram in Preview mode → Edit — auto-detects the diagram type and opens the correct builder.
• Fullscreen / Export: hover a rendered diagram → Full screen — pan/zoom, download SVG/PNG/.mmd, or copy Mermaid to clipboard.
• Import Gliffy: toolbar Import Gliffy button (all diagram types) or Rich editor toolbar Gliffy button — converts .gliffy JSON to Mermaid; shows a preview before applying. Supported types: flowchart, sequence, ER, org chart. Conversion is lossy (layout and colours discarded).
• wikied convert CLI: wikied convert --input diagram.gliffy --output diagram.md — converts a Gliffy file to a Markdown file with a Mermaid block. Warnings go to stderr; errors exit 1.

Export

• Export button (visible only in Preview mode, left of Save): opens a format dropdown.
  • Export as PDF — opens the browser print dialog (best quality for Mermaid SVG diagrams).
  • Export as DOC — downloads a .docx file (Microsoft Word–compatible).
  • Export as HTML — downloads a self-contained .html file with images embedded as base64 and Mermaid diagrams inlined as SVG.
• All formats use a clean neutral document style; filename is derived from the open file.

Dirty State and Saving

• Dirty indicators: orange dot beside the filename pill, orange badge count on the Save button, "Unsaved" badge in the status bar, orange filename in the file tree.
• Save button (floppy-disk icon): popover offers Save (current file) and Save all; shows dirty-count badge.
• Autosave: optional, enabled in Settings; triggers 750 ms after typing stops.
• Ctrl+S / Cmd+S saves the active file.
• Unsaved edits survive file switches via an in-memory content cache; switching back to a previously edited file restores those edits.

Git Integration

• Git button (visible when the workspace is a git repository): badge shows changed-file count; updates on every save and every 10 seconds.
• Popover offers: Commit (opens message modal, runs git add -A && git commit), Push, and Pull. Errors and results shown inline.
• Clone-on-empty-root modal: when the workspace is empty, the browser prompts to clone a repository URL or start empty.

Panels

• Outline panel: lists headings from the active document; supports heading search; opens as a right-side Drawer or pins to the Aside.
• Recent panel: lists the 10 most recently opened files; click to reopen; opens as a Drawer or pins to the Aside.
• Only one panel can be pinned at a time.

Navigation and Help

• Settings popover: accent color swatches, color scheme selector (System / Light / Dark), autosave toggle.
• Help modal: in-app user guide covering all major features and keyboard shortcuts.
• About modal: app description and version.
• Status bar: active file path, Saved/Unsaved badge, current mode, Markdown, UTF-8, LF, Local only.

Server Features

• Path safety on all filesystem operations (traversal, symlink escape, root-bounds checks).
• Revision conflict detection: save is rejected if the file changed on disk since it was loaded.
• UTF-16 LE BOM decoding: files saved by Windows tools render correctly; always written back as UTF-8.
• REST API: health, file tree, file content read/write, file create, rename, asset copy, git status/commit/push/pull, settings load/save.

Known Gaps

• Save conflict responses are not yet routed into the ConflictView component.
• The asset-copy API and rich editor image controls exist but are not connected end-to-end.
• The right aside is fixed at 300 px; drag-to-resize is not yet implemented.
• No project-wide full-text search, broken-link report, or multi-document tab management.