Pierwsza natywna wtyczka Markdown o wysokiej wydajności dla JavaScript

Wtyczka edytora tekstu Markdown, która przekształca natywny obszar tekstowy w pełny zestaw do edycji — nie wymaga synchronizacji. WYSIWYG i zwykłe tryby Markdown, podgląd na żywo, znajdź i zamień, obsługa RTL, tryb ciemny. Współpracuje z Django, Laravel, Rails, Node.js, PHP i dowolnym stosem.

Instalacja

NPM (bundlery: Vite, webpack, Rollup itp.)

npm install markdown-text-editor

1
2

import MarkdownEditor from 'markdown-text-editor';
new MarkdownEditor('#markdown-editor');

CDN: moduł ES

1
2
3
4

<script type="module">
  import MarkdownEditor from 'https://cdn.jsdelivr.net/npm/markdown-text-editor/+esm';
  new MarkdownEditor('#markdown-editor');
</script>

CDN: globalny znacznik skryptu (IIFE)

Nie ma potrzeby importowania — MarkdownEditor jest automatycznie dostępny jako zmienna globalna.

1
2
3
4
5
6
7
8
9

<form action="/api/save" method="POST">
  <textarea id="markdown-editor" name="content"># Hello World</textarea>
  <button type="submit">Save Content</button>
</form>

<script src="https://cdn.jsdelivr.net/npm/markdown-text-editor"></script>
<script>
  new MarkdownEditor('#markdown-editor');
</script>

Wersja demonstracyjna edytora Markdown

Szybki start

Przekaż obiekt opcji, aby dostosować edytor. Wszystkie opcje są opcjonalne — pomiń którąkolwiek, aby użyć wartości domyślnej.

1
2
3
4

const editor = new MarkdownEditor('#markdown-editor', {
  placeholder: 'Write your markdown...',
  toolbar: ['heading', 'bold', 'italic', 'strikethrough', 'ul', 'ol', 'checklist', 'blockquote', 'link', 'preview'],
});

Filozofia: „Najpierw rodzimy”

Większość redaktorów łamie standardowy przepływ pracy w sieci. MarkdownEditor to uwzględnia. Ponieważ znajduje się on bezpośrednio nad <textarea>, nie musisz uczyć się nowego sposobu obsługi danych.

• Nie jest potrzebne wiązanie danych: od razu po wyjęciu z pudełka współpracuje z <form method="POST">
• Dostęp standardowy: użyj document.getElementById('editor').value tak jak normalnego wejścia.
• Niezależny od backendu: działa z dowolnym backendem (Python, Node.js, PHP itp.), tak jak normalne pole formularza

MarkdownEditor kontra EasyMDE / SimpleMDE

Większość edytorów przecen JavaScript — EasyMDE, SimpleMDE, edytory oparte na CodeMirror — Zastąp <textarea> elementem niestandardowym. Oznacza to przerwy w przesyłaniu formularza, .value nic nie zwraca i musisz napisać dodatkowy kod, aby ponownie odczytać zawartość. MarkdownEditor jest inny — ulepsza istniejący obszar tekstowy i nigdy go nie zastępuje.

Integracja frameworków

Ponieważ MarkdownEditor zachowuje natywny <textarea>, integruje się z każdym frameworkiem zaplecza bez dodatkowego kodu. Twój serwer otrzymuje treść przeceny dokładnie tak samo, jak z dowolnego standardowego pola formularza.

Django

Dodaj class do widżetu obszaru tekstowego i zainicjuj edytor — request.POST['content'] działa bez dodatkowych kroków.

1
2
3
4
5
6
7
8

# forms.py
class PostForm(forms.ModelForm):
    class Meta:
        model = Post
        fields = ['content']
        widgets = {
            'content': forms.Textarea(attrs={'class': 'markdown-editor'}),
        }

1
2

new MarkdownEditor('.markdown-editor');
// request.POST['content'] contains the markdown on submit

Laravel

Użyj f.text_area z klasą — $request->input('content') odbiera bezpośrednio przecenę.

1
2

<textarea name="content" class="markdown-editor">{{ old('content') }}</textarea>
<script>new MarkdownEditor('.markdown-editor');</script>

Ruby on Rails

Współpracuje z form_with od razu po wyjęciu z pudełka — params[:content] zawiera przecenę. W przypadku Turbo Drive użyj turbo:load zamiast DOMContentLoaded.

1
2
3
4
5
6

document.addEventListener('turbo:load', () => {
    document.querySelectorAll('.markdown-editor:not([data-mde-init])').forEach(el => {
        el.setAttribute('data-mde-init', 'true');
        new MarkdownEditor(el);
    });
});

Node.js / Express

req.body.content otrzymuje przecenę po przesłaniu formularza — bez etapu synchronizacji, bez niestandardowej ekstrakcji.

1
2
3

<textarea name="content" class="markdown-editor"></textarea>
<script src="https://cdn.jsdelivr.net/npm/markdown-text-editor"></script>
<script>new MarkdownEditor('.markdown-editor');</script>

PHP

$_POST['content'] działa dokładnie tak samo jak każdy standardowy obszar tekstowy — wystarczy go dodać, a obsługa istniejącego formularza nie będzie wymagała żadnych zmian.

1
2
3
4
5
6

<form method="POST" action="save.php">
  <textarea name="content" class="markdown-editor"></textarea>
  <button type="submit">Save</button>
</form>
<script src="https://cdn.jsdelivr.net/npm/markdown-text-editor"></script>
<script>new MarkdownEditor('.markdown-editor');</script>

Konfiguracja

Możesz w pełni dostosować zachowanie i interfejs edytora, przekazując obiekt options. Jeśli pominiesz opcję, zostanie użyta wartość domyślna.

🛠 Dostosowywanie paska narzędzi

Pasek narzędzi jest modułowy. Modyfikując tablicę, możesz stworzyć minimalne środowisko lub w pełni funkcjonalny pakiet mocy.

Dostępne narzędzia

Informacje o narzędziu

💡 Wskazówki dotyczące wdrożenia:

• Zmiana kolejności: przyciski pojawiają się dokładnie w takiej kolejności, w jakiej zostały wymienione w tablicy
• Usuwanie: po prostu pomiń dowolny klucz (np. image) z tablicy, aby całkowicie wyłączyć tę funkcję dla użytkownika
• Natywna rezerwa: jeśli nie podasz placeholdera w JS, wtyczka automatycznie użyje atrybutu placeholder z Twojego <textarea> kodu HTML

📊 Stopka (pasek stanu)

Stopka znajduje się pod edytorem i pokazuje linię, kolumnę kursora, liczbę znaków dokumentu i opcjonalnie liczbę słów – wszystko aktualizowane w czasie rzeczywistym. Jest ona domyślnie widoczna i każdą statystykę można przełączać niezależnie.

Przykłady użycia

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

// Default — line, col, and chars visible
new MarkdownEditor('#editor');

// Disable the footer entirely
new MarkdownEditor('#editor', { footer: false });

// Hide only character count
new MarkdownEditor('#editor', { footer: { chars: false } });

// Hide line and column, keep character count
new MarkdownEditor('#editor', { footer: { line: false, col: false } });

// Show only line number
new MarkdownEditor('#editor', { footer: { col: false, chars: false } });

// Enable word count alongside the defaults
new MarkdownEditor('#editor', { footer: { words: true } });

// Show word count only
new MarkdownEditor('#editor', { footer: { line: false, col: false, chars: false, words: true } });

🔀 Tryby edycji

MarkdownEditor oferuje dwa różne sposoby pisania i formatowania treści. Możesz przełączać się między tradycyjnym widokiem skupionym na składni lub nowoczesnym, opartym na wizualizacjach.

• plain (Domyślne): czyste, wydajne środowisko Markdown, w którym widoczna jest składnia (taka jak **bold** lub # nagłówek). Idealny dla programistów i purystów Markdown
• hybrid: środowisko inspirowane WYSIWYG, które renderuje formatowanie (pogrubienie, kursywa, nagłówki) w czasie rzeczywistym podczas pisania, zachowując jednocześnie podstawową strukturę Markdown.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

// Default initialization (Plain Mode)
new MarkdownEditor('#markdown-editor');

// Explicit Plain Mode
new MarkdownEditor('#markdown-editor', {
    mode: 'plain'
});

// Hybrid (Visual) Mode
new MarkdownEditor('#markdown-editor', {
    mode: 'hybrid'
});

Podgląd trybu hybrydowego i zwykłego:

Tryb hybrydowy

Formatowanie wizualne jest renderowane w czasie rzeczywistym podczas pisania.

Tryb zwykły (domyślny)

Koncentruje się na surowej składni Markdown, aby zapewnić lekkość.

🌙 Tematyka

MarkdownEditor automatycznie dziedziczy motyw z otaczającej strony — nie jest wymagana żadna konfiguracja. Edytor odczytuje data-theme od najbliższego przodka podczas inicjalizacji, dzięki czemu pozostaje zsynchronizowany z motywem Twojej witryny od razu po wyjęciu z pudełka.

Sposób rozwiązania tematu (kolejność priorytetów)

1. theme opcja — jawne nadpisanie przekazane w obiekcie opcji
2. data-theme na <textarea> — ustawiane bezpośrednio na elemencie
3. data-theme na dowolnym przodku — np. <html>, <body> lub opakowanie <div>

Dostępne motywy

'jasny' (domyślnie), 'ciemny', 'jasny', 'ciemny'

Opcja 1 — dziedzicz z <html> lub dowolnego przodka (konfiguracja zerowa)

1
2
3
4
5
6

<html data-theme="dark">
  ...
  <textarea id="markdown-editor"></textarea>
  <script>
    new MarkdownEditor('#markdown-editor'); // picks up dark automatically
  </script>

Opcja 2 — ustaw data-theme bezpośrednio na <textarea>

1
2
3
4

<textarea id="markdown-editor" data-theme="dark"></textarea>
<script>
  new MarkdownEditor('#markdown-editor');
</script>

Opcja 3 — jawna opcja theme (zastępuje wszystko)

1
2
3

new MarkdownEditor('#markdown-editor', {
    theme: 'dark'
});

🎨 Motyw niestandardowy za pomocą zmiennych CSS

Możesz w pełni dostosować wygląd edytora, zastępując jego zmienne CSS w elemencie .markdown-editor-wrapper lub dowolnym selektorze [data-theme]. Wszystkie kolory wykorzystują przestrzeń kolorów OKLCH, aby uzyskać spójne percepcyjnie rezultaty.

Przykład niestandardowego motywu

Zastąp dowolną zmienną w .markdown-editor-wrapper po zainicjowaniu edytora lub zdefiniuj niestandardowy blok [data-theme] w swoim arkuszu stylów:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

/* Override individual variables */
.markdown-editor-wrapper {
    --color-primary: oklch(60% 0.2 30);   /* orange accent */
    --border-radius: 0.5rem;
}

/* Or define a full custom theme */
[data-theme="brand"] .markdown-editor-wrapper,
.markdown-editor-wrapper[data-theme="brand"] {
    --color-base:       oklch(15% 0.01 250);
    --color-on-base:    oklch(95% 0 0);
    --color-primary:    oklch(65% 0.22 145);   /* green */
    --color-on-primary: oklch(10% 0 0);
    --color-accent:     oklch(75% 0.18 60);
    --color-neutral:    oklch(80% 0 0);
    --border-radius:    0.75rem;
}

new MarkdownEditor('#markdown-editor', { theme: 'brand' });

Interfejs API treści

Jedną z głównych zalet MarkdownEditor jest to, że zapewnia doskonałą synchronizację podstawowego <textarea>. Niezależnie od tego, czy używasz nowoczesnego frameworku JavaScript, czy tradycyjnego backendu, takiego jak Django, PHP czy Laravel, przepływ pracy pozostaje prosty i natywny.

Czytanie i pisanie treści

1. Sposób rodzimy (zalecany)

Ponieważ edytor rozszerza standardowy obszar tekstowy, możesz używać znanych metod DOM. To najszybszy sposób na interakcję z danymi bez konieczności poznawania nowego API.

1
2
3
4
5

// Retrieve content via ID
const markdown = document.getElementById('markdown-editor').value;

// Set content via ID (The editor UI updates automatically)
document.getElementById('markdown-editor').value = "# New Heading Content";

2. Używanie odniesienia do zmiennej

Jeśli masz odwołanie do elementu Textarea, możesz go użyć bezpośrednio — nie jest potrzebny żaden interfejs API specyficzny dla biblioteki.

1
2
3
4
5
6
7

const textarea = document.getElementById('markdown-editor');

// Retrieve content
const markdown = textarea.value;

// Set content (the editor UI reflects this immediately)
textarea.value = "## Updated via JS";

3. Ustawianie początkowej zawartości po stronie serwera

Zalecanym sposobem ustawienia treści początkowej jest bezpośrednio w kodzie HTML <textarea> — działa to naturalnie z każdym frameworkiem backendowym (Django, Laravel, Rails, PHP itp.), a edytor renderuje ją automatycznie podczas init.

1
2

<!-- Recommended: set content server-side -->
<textarea id="markdown-editor"># Hello World</textarea>

Aby przeczytać lub zaktualizować treść w czasie wykonywania, użyj natywnej wartości textarea. Po aktualizacji wywołaj editor.render(), aby odświeżyć podgląd i warstwę hybrydową.

1
2
3
4
5
6
7
8

const textarea = document.getElementById('markdown-editor');

// Read
const markdown = textarea.value;

// Update at runtime
textarea.value = '# New content';
editor.render();

4. Zburzenie edytora — destroy()

Wywołaj funkcję editor.destroy(), aby usunąć opakowanie DOM edytora i przywrócić oryginalny <textarea> do jego pozycji w dokumencie. Przydatne w aplikacjach jednostronicowych podczas odmontowywania widoku.

1
2
3
4

const editor = new MarkdownEditor('#markdown-editor');

// Remove the editor and restore the plain textarea
editor.destroy();

Reagowanie na zmiany za pomocą onChange

Przekaż wywołanie zwrotne onChange, aby otrzymywać powiadomienia o każdej zmianie treści. Odbiera bieżący ciąg przeceny.

1
2
3
4
5

const editor = new MarkdownEditor('#markdown-editor', {
    onChange(value) {
        console.log('Content changed:', value.length, 'characters');
    }
});

Wersja robocza jest automatycznie zapisywana w localStorage

Użyj onChange, aby zapisać wersję roboczą przy każdym naciśnięciu klawisza. Przywróć go, wypełniając obszar tekstowy przed inicjalizacją edytora.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

const DRAFT_KEY = 'my-page-draft';

// Restore saved draft before init (only if textarea starts empty)
const textarea = document.getElementById('markdown-editor');
const saved = localStorage.getItem(DRAFT_KEY);
if (saved && !textarea.value) textarea.value = saved;

// Save on every change
const editor = new MarkdownEditor('#markdown-editor', {
    onChange(value) {
        localStorage.setItem(DRAFT_KEY, value);
    }
});

// Clear draft after successful form submission
document.querySelector('form').addEventListener('submit', () => {
    localStorage.removeItem(DRAFT_KEY);
});

Przesyłanie formularza

Ponieważ MarkdownEditor jest zbudowany bezpośrednio na natywnym <textarea>, jest kompatybilny z każdym frameworkiem backendowym (Django, Laravel, PHP, Ruby on Rails itp.) od razu po wyjęciu z pudełka.

Tutaj błyszczy filozofia „Native-First”. Nie musisz ręcznie synchronizować danych przed przesłaniem formularza. Przeglądarka traktuje edytor dokładnie tak, jak standardowe pole wejściowe.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

<form method="POST" action="/api/submit">
  <textarea id="markdown-editor" name="content" class="h-48" rows="5">
    # Initial Content
  </textarea>

  <button type="submit">Submit to Server</button>
</form>

<script>
  // Just initialize it. That's it.
  new MarkdownEditor('#markdown-editor');
</script>

Uwaga: inicjalizacja wtyczki MarkdownEditor jest obowiązkowa

Po prostu użyj standardowego <formularz> HTML. Atrybut name w obszarze tekstowym jest tym, czego Twój serwer użyje do identyfikacji treści.

🚀 Dlaczego to zmienia zasady gry dla backendów

Ponieważ edytor zachowuje natywne zachowanie <textarea>, serwer obsługuje dane jako standardowy ciąg znaków. Nie jest wymagana żadna dodatkowa logika — nie ma preventDefault() ani ręcznej konstrukcji FormData.

💡 Dlaczego jest to „funkcja zabójcza”:

Większość edytorów (np. Quill, Editor.js, simpleMDE, easyMDE) zapisuje dane w złożonych strukturach JSON. Jeśli programista z nich korzysta, musi przepisać schemat bazy danych i logikę renderowania.

Dzięki MarkdownEditor programista może wykorzystać starą witrynę i zastąpić zwykły <textarea> Twoim edytorem, a backend nawet nie zauważy, że się to zmieniło. Po prostu otrzymuje ten sam surowy tekst, co zawsze, ale użytkownik otrzymuje 10 razy lepsze wrażenia.

🖼️ Zaawansowane przesyłanie obrazu

Natywna obsługa przesyłania obrazów — zamiast polegania na wolnych, obciążających pamięć ciągach Base64 — to znacząca korzyść zarówno pod względem wydajności, jak i SEO.

Opcje konfiguracji

Narzędzie do tworzenia obrazów obsługuje konfigurację fileInput do obsługi bezpośredniego przesyłania na serwer.

• accept: zdefiniuj tablicę dozwolonych formatów obrazów (np. „webp”, „avif”)
• uploadUrl: Określ punkt końcowy zaplecza, do którego obiekt File zostanie wysłany za pośrednictwem POST
• params: opcjonalny obiekt do wysyłania dodatkowych danych (takich jak tokeny CSRF, identyfikatory użytkowników lub nazwy folderów) wraz z plikiem obrazu

Przykład użycia (pełna konfiguracja)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

const options = {
  placeholder: 'Start writing...',
  toolbar: [
    'link',
    {
      image: {
        fileInput: {
            accept: ['webp', 'avif'], // restrict the image upload format
            uploadUrl: '/api/upload', // Your upload endpoint
            params: {
                _token: 'your_csrf_token_here', // Essential for Laravel/Django
                folder: 'blog_posts'
            }
        },
        // Supports boolean: true/false OR object: { required: true }
        altInput: { required: true }
      }
    },
    'preview'
  ],
}
const editor = new MarkdownEditor('#markdown-editor', options);

📡 Integracja serwerów

Żądanie

Edytor wysyła żądanie POST jako multipart/form-data. Domyślnie zawiera:

• image_file: Rzeczywisty obiekt pliku
• image_alt: tekst alternatywny wprowadzony przez użytkownika
• ...plus wszelkie niestandardowe dane zdefiniowane w obiekcie params

Wymagana odpowiedź

Aby potwierdzić pomyślne przesłanie i wstawić obraz do edytora, Twój serwer musi zwrócić następującą strukturę JSON:

1
2
3
4

{
  "success": true,
  "image_path": "https://cdn.yourdomain.com/uploads/image.webp"
}

Uwaga: upewnij się, że używasz klucza image_path jako adresu URL przesłanego obrazu.

Walidacja tekstu alternatywnego obrazu (altInput)

Aby mieć pewność, że Twoje treści pozostaną dostępne i przyjazne dla SEO, MarkdownEditor domyślnie wymusza sprawdzanie poprawności tekstu alternatywnego.

• Zachowanie domyślne: jeśli nie zdefiniowano altInput, domyślnie jest to { wymagane: true
• Wymuś dostępność: użytkownicy nie będą mogli wstawić obrazu, dopóki nie zostanie podany opis alternatywny

1. Domyślne (nie wymaga konfiguracji)

1
2
3
4

// Alt text is REQUIRED by default
image: {
  fileInput: { uploadUrl: '/api/upload' }
}

2. Skrót (wyłącz weryfikację)

Jeśli chcesz zezwolić na obrazy bez opisów, po prostu ustaw wartość logiczną na false.

1
2
3

image: {
  altInput: false // Users can now skip the alt text field
}

3. Oparte na obiektach (jawne)

1
2
3
4
5

image: {
    altInput: {
        required: false // Disables alt text validation — users can skip the alt field
    }
}

Standardowe użycie obrazu (bez fileInput)

Jeśli fileInput nie jest skonfigurowane, edytor domyślnie korzysta z prostego modalu opartego na adresie URL. Jest to idealne rozwiązanie, jeśli Twoi użytkownicy głównie łączą się z zewnętrznymi hostami obrazów.

1
2
3
4
5
6
7
8

const options = {
  toolbar: [
    'link',
    'image',
    'preview'
  ],
}
const editor = new MarkdownEditor('#markdown-editor', options);

💡 Po co używać parametrów?

W frameworkach takich jak Laravel czy Django nie można przesyłać plików bez tokena CSRF. Dodając _token do obiektu params, Twoje żądanie bezproblemowo przejdzie przez oprogramowanie pośredniczące bezpieczeństwa zaplecza, zachowując filozofię „Zero Logic” dla kontrolerów po stronie serwera.

⌨️ Skróty klawiaturowe

Typowe czynności formatowania można uruchomić bezpośrednio z klawiatury, bez dotykania paska narzędzi. Każdy skrót jest także pokazany w podpowiedzi odpowiedniego przycisku na pasku narzędzi.

🔍 Znajdź i amp; Zastępować

W edytorze dostępny jest wbudowany panel wyszukiwania i zamiany — nie jest potrzebne żadne rozszerzenie przeglądarki ani osobne narzędzie.

• Naciśnij Ctrl + F (lub ⌘ F), aby otworzyć panel Znajdź
• Naciśnij Ctrl + H (lub ⌘ H), aby otworzyć Find & Wymień panel
• Wyszukiwanie nie uwzględnia wielkości liter i wyświetla licznik meczów na żywo (np. 3 z 12)
• Nawiguj po dopasowaniach za pomocą przycisków ▲ / ▼ lub Enter / Shift + Enter
• Opcja Zamień zastępuje aktualnie podświetlone dopasowanie; Opcja Zamień wszystko zastępuje wszystkie wystąpienia na raz
• Naciśnij Escape, aby zamknąć panel i powrócić do edytora

Panel unosi się w prawym górnym rogu obszaru zawartości edytora i nie zakłóca pisania.

Cechy

Przykład pełnej konfiguracji

Użyj tego obszernego przykładu, aby zainicjować MarkdownEditor ze wszystkimi podstawowymi funkcjami, w tym niestandardową kolejnością pasków narzędzi i zaawansowaną obsługą przesyłania obrazów.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

const editor = new MarkdownEditor('#markdown-editor', {
    mode: 'hybrid',
    placeholder: 'Start writing...',
    footer: {
        line: true,
        col: true,
        chars: true,
        words: true,
    },
    onChange(value) {
        console.log('Content updated:', value.length, 'characters');
    },
    toolbar: [
        'heading', 'bold', 'italic', 'strikethrough', 'blockquote',
        'ul', 'ol', 'checklist',
        'code', 'codeblock', 'hr', 'table',
        {
            image: {
                fileInput: {
                    accept: ['webp', 'avif', 'png'],
                    uploadUrl: '/api/upload'
                }
            }
        },
        'link', 'undo', 'redo', 'indent', 'outdent', 'preview'
    ],
});

// Read content natively
const markdown = document.getElementById('markdown-editor').value;

// destroy() when the view unmounts (SPAs)
// editor.destroy();