Forem: Mirone

Markdown editor for freedom!

Mirone — Wed, 22 Dec 2021 05:53:36 +0000

Long Live Markdown

The content editor is a very important function for the authoring platform. A powerful editor allows creators to focus on creation. And one of the best ways to please programmer creators is to support Markdown writing, because most programmers use Markdown to write articles.

Markdown, as a programmer’s love for writing, has many advantages:

Typesetting is achieved through grammar, no need to click to manually set the style
Quickly implement complex content, such as: code blocks, hyperlinks, formulas, etc.
Give creators more time to focus on content

However, the same has some disadvantages:

There is a certain learning threshold, not very friendly to non-programmers
Looking at the original document is like looking at the "code", the preview effect requires tool or editor support

Is there a way to keep the convenience brought by Markdown while lowering the barriers to entry? Most old players will blurt out: Typora.

Typora is great, however, it isn't free anymore. And because of that it is not open source, if you want to implement a similar Markdown editor in your own project, you need to find another solution.

Introducing Milkdown

Milkdown is a WYSIWYG (what you see is what you get) editor.
It's an open source project that integrates Markdown editor, components, and plugins.

Github repo: https://github.com/Saul-Mirone/milkdown

It has all the functions you want, and the functions you don't need can also be reduced by deleting plugins. The design idea of the plugin allows you to customize the Markdown editor most suitable for you in several minutes!

📝 WYSIWYG Markdown - Write markdown in an elegant way
🎨 Themable - Theme can be shared and used with npm packages
🎮 Hackable - Support your awesome idea by plugin
🦾 Reliable - Built on top of prosemirror and remark
⚡ Slash & Tooltip - Write fast for everyone
🧮 Math - LaTeX math equations support
📊 Table - Table support with fluent ui
📰 Diagram - Diagram support with mermaid
🍻 Collaborate - Shared editing support with yjs
💾 Clipboard - Support copy and paste markdown
👍 Emoji - Support emoji shortcut and picker

Get Started

We provide two ways for you to try it out:

Show Case

Table Editing

Copy and Paste as Markdown

Collaborative Editing

Two Way Binding

Drag and Drop

Build You Own Editor

First you need to create a new project, here I recommend you to use vite.

npm init vite@latest my-milkdown-app -- --template vanilla

The core of Milkdown and various plugins are independent NPM packages, which can be installed directly through NPM.

npm i @milkdown/core @milkdown/preset-commonmark @milkdown/theme-nord

Then you can create your own milkdown editor:

import { Editor } from '@milkdown/core';
import { nord } from '@milkdown/theme-nord';
import { commonmark } from '@milkdown/preset-commonmark';

Editor
  .make()
  .use(nord)
  .use(commonmark)
  .create();

Plugin is the first class member of Milkdown, it is essentially a plugin loader, and all functions are provided through plugins. A table is a plugin, a theme is a plugin, and even a simple line of text is also a plugin.

At present, the official has provided many plug-ins to ensure that they can be used out of the box. Only some plugins are listed below:

name	description
@milkdown/preset-commonmark	Add commonmark syntax support
@milkdown/preset-gfm	Add gfm syntax support
@milkdown/plugin-history	Add undo & redo support
@milkdown/plugin-clipboard	Add markdown copy & paste support
@milkdown/plugin-cursor	Add drop & gap cursor
@milkdown/plugin-listener	Add listener support
@milkdown/plugin-collaborative	Add collaborative editing support
@milkdown/plugin-table	Add table syntax support (already included in gfm)
@milkdown/plugin-prism	Add prism support for code block highlight
@milkdown/plugin-math	Add LaTeX support for math
@milkdown/plugin-tooltip	Add selected tooltip for text
@milkdown/plugin-slash	Add slash commands support
@milkdown/plugin-emoji	Add emoji support
@milkdown/plugin-diagram	Add mermaid diagram support
@milkdown/plugin-indent	Add tab indent support
@milkdown/plugin-upload	Add drop and upload support

You can also create your own plugin following this guide:

Writing Syntax Plugins

Conclusion

Before starting this project, I tried various Markdown editors, but I didn't find one that was particularly satisfactory. Because they are all closed source, and the functions are provided by the developers, some functions are too bloated, and some are too simple. In this case, I simply made a Markdown editor that can be easily customized and can be easily used by non-programmers, and I have the Milkdown that everyone sees.

I hope that the open source Milkdown will give users more freedom of choice and break the "monopoly" of the Markdown editor. Open source is not easy. If Milkdown is helpful to you, please give it a star✨.

https://github.com/Saul-Mirone/milkdown

How to design a Type Friendly Context

Mirone — Tue, 03 Aug 2021 16:41:15 +0000

Read this blog on my website.

In the world of JavaScript, Koa is a milestone. Although sinatra is born before it, Koa makes it really popular that apps should built by a simple core to load plugins, and bundles of plugins to implement unique features.
Today lots of apps are built with this pattern.
For example, vscode and webpack.

Context in JavaScript

In the world of Koa, ctx is a magic box 🔮. Users can get all sorts of properties on it. For example, you can get ctx.session if you install the koa-session plugin. And you can get ctx.request.body if you install the koa-body plugin.

A typical Koa plugin (also known as middleware) will be like:

app.use(async (ctx, next) => {

    // inject props into ctx
    ctx.foo = 'bar';

    const startTime = Date.now();

    await next();

    // do something after other ctx done.
    const endTime = Date.now();
    const duration = endTime - startTime;

    console.log('Ctx duration:', duration);
})

Static Type Checking

Everything seems perfect until static type system join the game,
which is bring in by TypeScript and Flow. With the safe type checking and powerful editor lsp features, people use them to build not only large systems, but also small apps and tools.

But when Koa meets static type checking, 💥 everything stop working. Type system cannot infer what property is really on ctx and what's not. For example, if I call ctx.foo, how do I know wether the plugin inject the foo property is loaded in current Koa app or not? What's more, users can't get the hint of the editor because the type system don't know what to suggest.

It's a common problem of languages with static type system:
how to handle object shared between modules elegantly?

Design

The key is using IoC. With this pattern we can inject type information into context.

Let's reconsider the design of context in koa, we can see that the context is an object with properties you can modify, such as ctx.foo. What if we transform this API into ctx.get(foo)? Since the creation of foo is what we can control, we can write some information on it.

So, let's assume the API of context is designed as this:

const ctx = createCtx();

const numberSlice = createSlice(0);

// inject a ctx.
ctx.inject(slice);

const number = ctx.get(numberSlice); // -> 0

// set value of numberSlice to 1.
ctx.set(numberSlice, number + 1);

I introduced you a new data structure: slice.
With this design, We just split up the entire ctx into several pieces of slices.

Now we can get define the structure of ctx and slice:

type Ctx = Map<symbol, Slice>;

type Slice<T = unknown> = {
    id: symbol;
    set: (value: T) => void;
    get: () => T;
}

Slice

Then, let's try to implement the slice:

type Metadata<T> = {
    id: symbol;
    (ctx: Ctx): Slice<T>;
};

const createSlice = <T>(defaultValue: T): Metadata<T> => {
    const id = Symbol('Slice');

    const metadata = (ctx: Ctx) => {
        let inner = defaultValue;
        const slice: Slice<T> = {
            id,
            set: (next) => {
                inner = next;
            },
            get: () => inner
        }
        ctx.set(id, slice as Slice);
        return slice;
    }
    metadata.id = id;

    return metadata;
}

We create a metadata that brings slice's information on it. And a slice factory that can be used to inject on context.

Ctx

The implementation of ctx will be much simpler:

const createCtx = () => {
    const map: Ctx = new Map();

    const getSlice = <T>(metadata: Metadata<T>): Slice<T> => {
        const value = map.get(metadata.id);
        if (!value) {
            throw new Error('Slice not injected');
        }
        return value as Slice<T>;
    }

    return {
        inject: <T>(metadata: Metadata<T>) => metadata(map),
        get: <T>(metadata: Metadata<T>): T => getSlice(metadata).get(),
        set: <T>(metadata: Metadata<T>, value: T): void => {
            getSlice(metadata).set(value);
        }
    }
}

We use a simple Map as the container of slices, with the symbol as key so the slices will not be conflict between each other.

Test

Now our context has been done, let's do some test:

const num = createSlice(0);
const ctx1 = createCtx();
const ctx2 = createCtx();

ctx1.inject(num);
ctx2.inject(num);

const x = ctx1.get(num); // editor will know x is number
ctx1.set(num, x + 1);

// this line will have an error since num slice only accept number
ctx.set(num, 'string')


ctx1.get(num); // => 1
ctx2.get(num); // => still 0

Now we have built a type friendly context using IoC, with slices that can be shared between context, but values will be isolated.

View full code on code sandbox.

Introducing Milkdown: A plugin driven WYSIWYG markdown editor

Mirone — Thu, 08 Jul 2021 18:46:29 +0000

Overview

Milkdown is a lightweight but powerful WYSIWYG markdown editor. It's made up by two parts:

A tiny core which provide markdown parser, serializer and kinds of plugin loader.
Lots of plugins provide syntax, commands and components.

With this pattern you can enable or disable any custom syntax you like, such as table, latex and slash commands.
You can even create your own plugin to support your awesome idea.

Features

📝 WYSIWYG Markdown - Write markdown in an elegant way
🎨 Themable - Theme can be shared and used with npm packages
🎮 Hackable - Support your awesome idea by plugin
🦾 Reliable - Built on top of prosemirror and remark
⚡️ Slash & Tooltip - Write fast for everyone, driven by plugin
🧮 Math - LaTeX math equations support, driven by plugin
📊 Table - Table support with fluent ui, driven by plugin

Tech Stack

Milkdown is built on top of these tools:

Prosemirror and it's community - A toolkit for building rich-text editors on the web
Remark and it's community - Markdown parser done right
Postcss - Powerful css tool to build theme
TypeScript - Developed by typescript
Prism - Code snippets support
Katex - LaTex math rendering

First editor

We have some pieces for you to create a very minimal editor:

We use material icon and Roboto Font in our theme.
Make sure to include them for having the best experience.

import { Editor } from '@milkdown/core';
import { commonmark } from '@milkdown/preset-commonmark';

// import theme
import '@milkdown/theme-nord/lib/theme.css';

const root = document.body;
new Editor({ root }).use(commonmark).create();

For further information, please visit our website.