README

Markian is a framework-independent Markdown editor and lightweight viewer. It stores ordinary Markdown and provides visual/source editing, tables, an outline, search, templates, mentions, and optional code and Mermaid workspaces.

The library is under development. Current APIs are documented below; unfinished features and acceptance checks are tracked in the implementation plan. Browser coverage does not yet establish cross-browser, real-device, screen-reader, or restrictive-CSP conformance.

Getting Started

Use the prebuilt files in dist with a static HTTP server. Consumers do not need Node.js, a bundler, or a build step.

<link rel="stylesheet" href="dist/markian.css">
<div id="notes" style="height: 480px"></div>
<script src="dist/markian.min.js"></script>
<script>
  const editor = Markian.create(document.querySelector('#notes'), {
    markdown: '# Notes\n\nReady for review.',
  });
  editor.ready.then(() => editor.focus());
</script>

Serve dist/markdown-github.css beside the script: Markian loads it by default. Await ready before commands or document replacement. A textarea is also a supported host; its value follows edits and native form reset.

To install the development package with Composer:

composer config repositories.markian vcs https://github.com/axenox/markian.git
composer require axenox/markian:@dev

Expose the installed package's dist files through your static asset routing. Tagged publication and Asset Packagist availability are not yet verified. See the examples guide for runnable pages and the development guide to work from source.

Configuration

Options belong to each instance. This example uses a compact toolbar, a custom content stylesheet, and local link suggestions:

const editor = Markian.create(document.querySelector('#notes'), {
  markdown: '# Notes',
  theme: 'dark',
  sidebarVisible: false,
  markdownCssUrls: ['/assets/markdown.css'],
  toolbar: [
    { id: 'format', type: 'group', items: ['bold', 'italic', 'link'] },
    { id: 'utilities', type: 'group', align: 'opposite', items: ['search', 'fullscreen'] },
  ],
  onLinkSuggest: ({ query }) => [
    { label: 'Guide', destination: 'guide.md' },
  ].filter(item => item.label.toLowerCase().includes(query.toLowerCase())),
});

All options, effective defaults, callbacks, and bundled extension settings are in the configuration reference.

Extensibility

Hosts and extensions use the same public API. The following example loads both bundled editor extensions and adds a custom command. The host must serve a trusted Mermaid 11+ runtime at the configured URL.

Optional Mermaid Extension

This example enables Mermaid alongside Code. Full renderer, safety, and workspace guidance is in the Mermaid guide.

<link rel="stylesheet" href="dist/markian.css">
<link rel="stylesheet" href="dist/extensions/mermaid.css">
<link rel="stylesheet" href="dist/extensions/code.css">
<div id="extended-notes" style="height: 480px"></div>
<script src="dist/markian.min.js"></script>
<script src="dist/extensions/code.min.js"></script>
<script src="dist/extensions/mermaid.min.js"></script>
<script>
  Markian.registerExtension('code', MarkianCode.codeExtension);
  Markian.registerExtension('mermaid', MarkianMermaid.mermaidExtension);
  const extendedEditor = Markian.create(document.querySelector('#extended-notes'), {
    markdown: '# Review',
    extensions: {
      code: { enabled: true, config: { tabWidth: 2 } },
      mermaid: { enabled: true, config: {
        source: '/assets/mermaid.min.js',
      } },
    },
  });
  extendedEditor.ready.then(() => {
    extendedEditor.getCommands().insert({
      id: 'review:example',
      label: 'Insert review example',
      icon: 'codeblock',
      views: ['visual'],
      mutates: true,
      run: instance => instance.insertCodeBlock('Review pending', 'text'),
    });
    extendedEditor.getToolbar().insert({ id: 'review:example' }, 'insert', 'rule');
  });
</script>

Callbacks connect host services; renderers and views add presentation; schema mappings extend supported structure. See customization examples and the contributor guide to writing extensions. Core templates and mentions need no optional script or backend. Inline HTML is limited to explicitly enabled attribute-free tags; generated-region providers remain unfinished.

API

The classic script exposes window.Markian, a factory rather than a singleton editor. Instances own their document, theme, history, callbacks, and lifecycle.

await editor.ready;
const unsubscribe = editor.on('change', event => {
  console.log(event.origin, editor.get());
});
await editor.whenIdle();
const markdown = editor.get();
unsubscribe();

get() includes pending source and block drafts, even while Help is visible. Hosts own persistence and must handle edits during any asynchronous save. See the complete API reference.

Lightweight Viewer

The viewer displays Markdown without constructing an editor. Load only its assets for display-only pages:

<link rel="stylesheet" href="dist/markian-viewer.css">
<article id="document"></article>
<script src="dist/markian-viewer.min.js"></script>
<script>
  const viewer = MarkianViewer.create(document.querySelector('#document'), {
    markdown: '# Notes\n\nReady for review.',
  });
</script>

Its source value is exact, tasks are noninteractive, and optional fence rendering is opt-in. Mermaid requires a separate render-only adapter. See viewer customization and viewer options.

Documentation

Current Limits

Visual editing can normalize Markdown syntax and line endings, but must retain meaningful content. Unsupported visual imports fall back to source rather than silently deleting content. Raw HTML is not trusted rendered content. The architecture describes preservation and safety policies.

Code workspaces currently target top-level fences. The optional Code extension includes separately loaded offline highlighting assets for JavaScript/TypeScript, JSON, CSS, HTML/XML, PHP, SQL, Python and YAML, plus a language menu and local source/language history. See the Code example and configuration. Mermaid is supplied by the host, never bundled into core. Host transport, authentication, storage, and framework widgets remain outside Markian. Full migration and production acceptance remain tracked in the requirements documents.

axenox / markian

Package info

Security

Statistics