Zaten sahip olduğunuz metin alanında araç çubuğu, canlı önizleme ve WYSIWYG

Form gönderimi, doğrulama ve gerekli alanların çalışmaya devam etmesi için metin alanınızı değiştirmek yerine geliştiren bir işaretleme düzenleyicisi. WYSIWYG ve düz Markdown modları, canlı önizleme, bul ve değiştir, RTL desteği, karanlık mod. Django, Laravel, Rails, Node.js, PHP ve herhangi bir yığınla bağımsız olarak çalışır.

Frutjam ve Tailwind gerekmez. Stiller paket halinde olduğundan editör herhangi bir projeye dahil olur.

Kurulum

NPM (paketleyiciler: Vite, webpack, Rollup vb.)

npm install markdown-text-editor

1
2

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

TypeScript tanımları paketle birlikte gelir; dolayısıyla seçenekler, araç çubuğu girişleri ve değişken şekiller, ekstra kurulum gerekmeden kontrol edilir ve otomatik olarak tamamlanır.

CDN: ES modülü

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: global komut dosyası etiketi (IIFE)

İçe aktarmaya gerek yok: MarkdownEditor otomatik olarak global bir değişken olarak kullanılabilir.

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>

Markdown Düzenleyici Demosu

Hızlı Başlangıç

Düzenleyiciyi özelleştirmek için bir seçenekler nesnesi iletin. Tüm seçenekler isteğe bağlıdır: varsayılan değeri kullanmak için herhangi birini atlayın.

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'],
});

Felsefe: "Önce Yerli"

Çoğu editör standart web iş akışını bozar. MarkdownEditor bunu benimsiyor. Çünkü doğrudan bir şeyin üstüne oturuyor. <textarea>, verileri işlemenin yeni bir yolunu öğrenmenize gerek yok.

• Veri Bağlamaya Gerek Yok: Şunlarla çalışır: <form method="POST"> kutunun dışında
• Standart Erişim: Kullanım document.getElementById('editor').value tıpkı normal bir giriş gibi.
• Arka Uç Agnostik: Normal bir form alanı gibi herhangi bir arka uçla (Python, Node.js, PHP vb.) çalışır

MarkdownEditor vs EasyMDE / SimpleMDE

Çoğu JavaScript işaretleme düzenleyicisi (EasyMDE, SimpleMDE, CodeMirror tabanlı düzenleyiciler) ** <textarea>** ve form gönderildiğinde içeriği geri yazarak bir kopyasını düzenleyin. Bu, başka bir şeyin değere ihtiyacı olana kadar işe yarar: a required tarayıcının odaklanamadığı alan gönderimi tamamen engeller ve .value veya FormData göndermeden önce oku, htmx, Turbo, otomatik kaydetme ve kaydedilmemiş değişiklik korumalarını bozan boş bir dize döndürür. MarkdownEditor farklıdır. Zaten sahip olduğunuz textarea'yi şekillendirir ve onu yazdığınız alan olarak bırakır, böylece değer her an doğru olur.

Çerçeve Entegrasyonu

MarkdownEditor yerel içeriği koruduğu için <textarea>, herhangi bir ekstra kod olmadan her arka uç çerçevesiyle bütünleşir. Sunucunuz işaretleme içeriğini tam olarak herhangi bir standart form alanından aldığı gibi alır. React ve Vue için bu bölümün sonunda ele alınan birkaç satır gerekir.

Django

Ekle class textarea widget'ınıza gidin ve düzenleyiciyi başlatın: request.POST['content'] ekstra adım gerektirmeden çalışır.

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

Kullanmak f.text_area bir sınıfla: $request->input('content') indirimi doğrudan alır.

1
2

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

Ruby on Rails

İle çalışır form_with kutunun dışında: params[:content] işaretlemeyi içerir. Turbo Tahrik için şunu kullanın: turbo:load yerine 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 / Ekspres

req.body.content form gönderiminde işaretlemeyi alır: senkronizasyon adımı yok, özel çıkarma yok.

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'] tam olarak herhangi bir standart textarea ile aynı şekilde çalışır: bırakın ve mevcut form işlemeniz sıfır değişiklik gerektirir.

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>

Tepki ver

Düzenleyiciyi bir efektte oluşturun ve bağlantıyı kestiğinizde onu yok edin. Kullanmak defaultValue yerine value: Düzenleyici doğrudan textarea'ya yazar, böylece kontrollü bir ciltleme kullanıcının yazdıklarının üzerine yazar.

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

import { useEffect, useRef } from 'react';
import MarkdownEditor from 'markdown-text-editor';

function MarkdownField({ name, defaultValue = '', onChange }) {
    const ref = useRef(null);

    useEffect(() => {
        const editor = new MarkdownEditor(ref.current, { onChange });
        return () => editor.destroy();
    }, []);

    return <textarea ref={ref} name={name} defaultValue={defaultValue} />;
}

Geri dönüyor editor.destroy() Bu efekt aynı zamanda geliştirme aşamasında efektleri iki kez çalıştıran ve aksi takdirde iki editörün bir metin alanında kalmasına neden olan StrictMode'u da kapsar. Boş bağımlılık dizisi kasıtlıdır: seçenekler düzenleyici oluşturulduğunda bir kez okunur, bu nedenle efektin yeniden çalıştırılması onu yıkıp her değişiklikte yeniden oluşturacaktır.

Vue

Aynı fikir. Başlangıç ​​değerini bir kez ayarlayın onMounted ve bağlama :valueveya geri gönderilen her tuş vuruşu v-model textarea'nın üzerine yazardı.

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

<script setup>
import { ref, onMounted, onBeforeUnmount } from 'vue';
import MarkdownEditor from 'markdown-text-editor';

const el = ref(null);
const props = defineProps({ modelValue: { type: String, default: '' } });
const emit = defineEmits(['update:modelValue']);
let editor = null;

onMounted(() => {
    el.value.value = props.modelValue;
    editor = new MarkdownEditor(el.value, {
        onChange: value => emit('update:modelValue', value)
    });
});

onBeforeUnmount(() => editor?.destroy());
</script>

<template><textarea ref="el"></textarea></template>

Olarak kullanılır <MarkdownField v-model="content" />. Sade bir biçimde atlayabilirsiniz v-model tamamen ve diğer çerçevelerde olduğu gibi, gönderim sırasında textarea'daki değeri okuyun.

Yapılandırma

Düzenleyicinin davranışını ve arayüzünü tamamen özelleştirebilirsiniz. options nesne. Bir seçeneği atlarsanız varsayılan değer kullanılır.

Editör oluşturulduğunda seçenekler bir kez okunur. Daha sonra bunları değiştirmenin hiçbir etkisi olmaz: ara destroy() ve bunun yerine yeni bir düzenleyici oluşturun.

🛠 Araç Çubuğu Özelleştirmesi

Araç çubuğu modülerdir. Diziyi değiştirerek minimal bir deneyim veya tam özellikli bir güç paketi oluşturabilirsiniz.

Mevcut Araçlar

Araç Referansı

💡 Uygulama İpuçları:

• Yeniden sıralama: Düğmeler, dizide listelediğiniz sırayla görünür
• Kaldırma: Herhangi bir tuşu çıkarmanız yeterlidir (örneğin image) bu özelliği kullanıcı için tamamen devre dışı bırakmak için diziden
• Yerel Geri Dönüş: Bir placeholder JS'de eklenti otomatik olarak placeholder HTML'nizdeki özellik <textarea>

📊 Alt Bilgi (Durum Çubuğu)

Altbilgi, düzenleyicinin altında bulunur ve imlecin satır, sütun, belgenin karakter sayısını ve isteğe bağlı olarak kelime sayısını gösterir; tümü gerçek zamanlı olarak güncellenir. Varsayılan olarak görünürdür ve her istatistik bağımsız olarak değiştirilebilir.

Kullanım Örnekleri

 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 } });

🔀 Düzenleme Modları

MarkdownEditor içeriğinizi yazmanız ve biçimlendirmeniz için iki farklı yol sunar. Geleneksel sözdizimi odaklı görünüm veya modern, görsel öncelikli deneyim arasında geçiş yapabilirsiniz.

• plain (Varsayılan): Sözdiziminin (gibi) olduğu temiz, yüksek performanslı bir Markdown ortamı **bold** veya # heading) görülebilir. Geliştiriciler ve Markdown'a sadık olanlar için ideal
• hybrid: Siz yazarken biçimlendirmeyi (Kalın, İtalik, Başlıklar) gerçek zamanlı olarak işleyen ve aynı zamanda temeldeki Markdown yapısını koruyan, WYSIWYG'den ilham alan bir deneyim.

 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'
});

Hibrit ve Düz Mod Önizlemesi:

Hibrit Mod

Siz yazarken görsel biçimlendirme gerçek zamanlı olarak oluşturulur.

Düz Mod (Varsayılan)

Hafif bir deneyim için ham Markdown sözdizimine odaklanır.

🌙 Temalama

MarkdownEditor temasını otomatik olarak çevresindeki sayfadan devralır: yapılandırma gerekmez. Editör okur data-theme Başlatma sırasında en yakın atadan gelir, böylece sitenizin temasıyla kutudan çıktığı haliyle senkronize kalır.

Tema nasıl çözümlenir (öncelik sırası)

1. theme seçenek: seçenekler nesnesinde iletilen açık geçersiz kılma
2. data-theme üzerinde <textarea>: doğrudan eleman üzerinde ayarlanır
3. data-theme herhangi bir atada: ör. <html>, <body>veya bir sarmalayıcı <div>

Mevcut temalar

'light' (varsayılan), 'dark', 'snowberry', 'darkberry'

Seçenek 1, devralın <html> veya herhangi bir ata (sıfır yapılandırma)

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>

Seçenek 2: ayarla data-theme doğrudan üzerinde <textarea>

1
2
3
4

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

Seçenek 3: açık theme seçenek (her şeyi geçersiz kılar)

1
2
3

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

🎨 CSS Değişkenleri aracılığıyla Özel Tema

Düzenleyicinin görünümünü, CSS değişkenlerini geçersiz kılarak tamamen özelleştirebilirsiniz. .markdown-editor-wrapper eleman veya herhangi [data-theme] seçici. Tüm renkler kullanılır OKLCH renk uzayı algısal olarak tekdüze sonuçlar için.

Özel tema örneği

Herhangi bir değişkeni geçersiz kıl .markdown-editor-wrapper editör başlatıldıktan sonra veya özel bir tanım tanımladıktan sonra [data-theme] stil sayfanızda engelle:

 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' });

🌐 Arayüz Dili

Editörün kendi metni, araç ipuçları, menü öğeleri, kalıcı alanlar ve düğmeler varsayılan olarak İngilizcedir. bir geçmek labels çevirmeye itiraz ediyorum. Anahtarlar, gettext'in çalışma şekli olan İngilizce dizelerdir, bu nedenle yalnızca değiştirmek istediklerinizi listelersiniz ve eksik olan her şey İngilizce'ye geri döner.

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

new MarkdownEditor('#markdown-editor', {
    labels: {
        'Bold': 'Gras',
        'Italic': 'Italique',
        'Heading': 'Titre',
        'Link': 'Lien',
        'Image link': 'Lien de l\'image',
        'URL': 'URL',
        'Alt text': 'Texte alternatif',
        'Apply': 'Appliquer',
        'Uploading...': 'Téléversement...',
    },
});

Bu, en çok sağdan sola içerikle birlikte önemlidir. Arapça, Urduca ve Farsça kendi başlarına doğru şekilde yerleştirilmiştir, ancak sağdan sola metin üzerinde hâlâ "Kalın" yazan araç çubuğunun yalnızca yarısı çevrilmiştir.

🏷 Değişkenler

Yer tutucuları eklemek için bir araç çubuğu açılır menüsü ekler. E-posta, fatura veya sözleşme şablonlarında olduğu gibi, belgeyi yazan kişi yer tutucu söz dizimini tanımlayan geliştirici olmadığında kullanışlıdır: okunabilir bir ad seçer ve kendisi için doğru söz dizimi eklenir.

1
2
3
4
5
6
7
8
9

new MarkdownEditor('#markdown-editor', {
    toolbar: ['bold', 'italic', 'link',
        { variables: [
            { label: 'Customer Name', value: '{{customer.name}}' },
            { label: 'Invoice No',    value: '{{invoice.number}}' }
        ]},
        'preview'
    ]
});

Araç, satır içi olarak yapılandırılmıştır. toolbar dizi, dolayısıyla diğer düğmeler arasındaki konumu size kalmış. Düğme etiketleri listeler ve bunlardan birine tıklamak onun etiketini ekler. value imleçte herhangi bir seçimin yerine geçer. Liste boşsa hiçbir şey oluşturulmaz.

Önizlemedeki örnek değerler

Verilen bir giriş sample bu örneği önizlemede gösterirken, textarea gerçek yer tutucuyu korur. Biri olmayan girişler yazılı olarak görünür, böylece her ikisini de karıştırabilirsiniz.

1
2
3
4
5
6
7

{ variables: [
    { label: 'Customer Name', value: '{{customer.name}}', sample: 'Hannes' },
    { label: 'Invoice No',    value: '{{invoice.number}}' }
]}

// textarea : Hi {{customer.name}}, invoice {{invoice.number}}
// preview  : Hi Hannes, invoice {{invoice.number}}

Gruplama

Bir giriş yapın items bir yerine value başlı bir bölüm oluşturmak için. Gruplandırılmış ve düz girişler tek bir listede karıştırılabilir.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{ variables: [
    { label: 'Today', value: '{{today}}', sample: '10 September 2026' },
    { label: 'Customer', items: [
        { label: 'Name',  value: '{{customer.name}}',  sample: 'Hannes' },
        { label: 'Email', value: '{{customer.email}}', sample: 'hannes@example.com' }
    ]},
    { label: 'Invoice', items: [
        { label: 'Number', value: '{{invoice.number}}' }
    ]}
]}

Bilinmesi gerekenler

• Düzenleyici hiçbir zaman değişkenleri çözmez. Metin ekler ve uygulamanız daha sonra, genellikle sunucu tarafında gerçek değerlerin yerine geçer. sample yalnızca önizlemenin görüntülediklerini etkiler.
• Etiketler düz metin olarak gösterilir, dolayısıyla etiketteki işaretleme hiçbir zaman oluşturulmaz.
• Yanlış biçimlendirilmiş girişler atılmak yerine atlanır ve kullanılabilir hiçbir şey yapılandırılmadığında düğme hiçbir şekilde oluşturulmaz.

🖋 Özel Oluşturucu

Önizleme şununla oluşturulur: işaretlenmiş ve ile dezenfekte edildi DOMpurify. Her ikisi de değiştirilebilir. Uygulamanız zaten başka bir kitaplıkla işaretleme oluşturduğunda ve önizlemenin üretimle tam olarak eşleşmesini istediğinizde bunu kullanın.

Her iki seçenek de bir dize alıp bir dize döndüren düz işlevlerdir; dolayısıyla herhangi bir ayrıştırıcı ve herhangi bir temizleyici çalışır.

1
2
3
4
5
6
7
8
9

import MarkdownIt from 'markdown-it';
import taskLists from 'markdown-it-task-lists';
import MarkdownEditor from 'markdown-text-editor';

const md = new MarkdownIt({ linkify: true, breaks: true }).use(taskLists);

new MarkdownEditor('#markdown-editor', {
    renderer: markdown => md.render(markdown)
});

DOMPurify hala çıkışta çalışıyor, böylece hiçbir şeyi yapılandırmanıza gerek kalmadan XSS korumasını koruyorsunuz.

Özel dezenfektan

Yalnızca varsayılan, oluşturucunuzun yaydığı bir şeyi çıkardığında gereklidir. DOMPurify şunları kaldırır <iframe> varsayılan olarak video yerleştirmelere açıkça izin verilmesi gerekir. Düzenleyiciyle birlikte gelen kopya dahili olduğundan DOMpurify'ın kendi kodunuzla içe aktarılması gerekir.

1
2
3
4
5
6
7
8
9

import DOMPurify from 'dompurify';

new MarkdownEditor('#markdown-editor', {
    renderer:  markdown => md.render(markdown),
    sanitizer: html => DOMPurify.sanitize(html, {
        ADD_TAGS: ['iframe'],
        ADD_ATTR: ['allow', 'allowfullscreen', 'frameborder']
    })
});

Paketleyici yerine bir komut dosyası etiketi kullanarak DOMPurify'ı düzenleyicinin yanına yükleyin:

1
2

<script src="https://cdn.jsdelivr.net/npm/dompurify"></script>
<script src="https://cdn.jsdelivr.net/npm/markdown-text-editor"></script>

Bilinmesi gerekenler

• Yalnızca önizleme. Karma modun canlı biçimlendirmesi ayrı bir dahili oluşturucu kullanır ve etkilenmez.
• Görev listelerinin eklenti desteğine ihtiyacı vardır. Tıklanabilir onay kutuları aranarak bulunur. input[type="checkbox"] çıktıda, yani işaretleme gerekiyor markdown-it-task-lists. Düzenleyici, görev listesi söz dizimini tespit ederse ve hiçbir onay kutusu tespit etmezse bir uyarıyı günlüğe kaydeder.
• Her ikisi de eşzamanlı olmalı ve bir dize döndürmelidir. Bir async fonksiyon yazıyor [object Promise] önizlemeye girin.
• Dezenfektanı değiştirmek korumanızın yerini alır. gibi bir geçiş html => html temizlemeyi tamamen devre dışı bırakır ve yalnızca tamamen güvenilen içerik için güvenlidir.

🎨 İç Elemanları Şekillendirmek

CSS değişkenleri, devralındıkları için çoğu temayı kapsar; dolayısıyla bir tanesini ayarlamak .markdown-editor-wrapper araç çubuğuna, düğmelere, önizlemeye ve alt bilgiye ulaşır. Yalnızca hiçbir değişken ihtiyacınız olanı ortaya çıkarmadığında bir sınıf adına ulaşın.

1
2
3
4
5

/* Variables set on the wrapper inherit down to every child */
.markdown-editor-wrapper {
    --border-radius: 12px;   /* rounds the editor and its toolbar buttons */
    --color-primary: oklch(60% 0.2 30);
}

Sınıf referansı

Bu sınıf adları istikrarlı ve stil açısından güvenlidir.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

/* Some variables are set by the component on itself, which beats an
   inherited value. Target the element directly for those. */
.markdown-editor-wrapper .markdown-btn {
    --btn--font-size: 0.875rem;
}

/* And use classes for anything no variable exposes */
.markdown-editor-wrapper .toolbar {
    border-bottom: 2px solid oklch(60% 0.2 30);
}

Bir düzenleyiciyi hedefleme

Bir sayfada birden fazla düzenleyici varken bunlardan birini hedefleyin data-editor. Sarmalayıcı, kimliğini yansıtır <textarea>, Bu yüzden <textarea id="notes"> sana verir [data-editor="notes"]. Kimliğin kendisi metin alanında kalır, bu nedenle getElementById çalışmaya devam ediyor.

1
2
3
4

/* one editor only */
[data-editor="notes"] {
    --border-radius: 0;
}

🪟 Tam Ekran ve Katmanlama (z-endeksi)

Tam ekranda düzenleyici şunu kullanır: z-index: 10000, çoğu kullanıcı arayüzü çerçevesinin sabit başlıklar ve kaplamalar için ayırdığı katmanları temizler. Sabit bir başlık veya kenar çubuğu hâlâ düzenleyiciyi kapsıyorsa bu değeri yükseltin.

Şununla geçersiz kıl: --mte-fullscreen-z-index. Değer yalnızca tam ekranda geçerlidir ve devralınır; dolayısıyla herhangi bir ataya ayarlanması, altındaki tüm düzenleyicileri kapsar.

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

/* every editor on the page */
.markdown-editor-wrapper {
    --mte-fullscreen-z-index: 20000;
}

/* one section only - the value inherits down */
#admin-panel {
    --mte-fullscreen-z-index: 20000;
}

/* a single editor, by its textarea id */
[data-editor="notes"] {
    --mte-fullscreen-z-index: 20000;
}

İçerik API'si

MarkdownEditor'ün temel güçlü yönlerinden biri, temeldeki bilgileri korumasıdır. <textarea> mükemmel şekilde senkronize edilmiştir. İster modern bir JavaScript çerçevesi ister Django, PHP veya Laravel gibi geleneksel bir arka uç kullanıyor olun, iş akışı basit ve yerel kalır.

İçerik Okuma ve Yazma

1. Yerel Yol (Önerilen)

Düzenleyici standart bir metin alanını geliştirdiğinden, tanıdık DOM yöntemlerini kullanabilirsiniz. Bu, yeni bir API öğrenmeden verilerinizle etkileşim kurmanın en hızlı yoludur.

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. Değişken Referans Kullanma

Textarea öğesine bir referansınız varsa onu doğrudan kullanabilirsiniz: kitaplığa özgü API gerekmez.

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. Başlangıç ​​içerik sunucusu tarafının ayarlanması

Başlangıç ​​içeriğini ayarlamanın önerilen yolu doğrudan <textarea> HTML: Bu, her arka uç çerçevesinde (Django, Laravel, Rails, PHP, vb.) doğal olarak çalışır ve düzenleyici bunu init'te otomatik olarak işler.

1
2

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

İçeriği çalışma zamanında okumak veya güncellemek için yerel textarea değer. Arama editor.render() önizleme ve hibrit katmanı yenilemek için bir güncellemeden sonra.

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. Editörü parçalamak: destroy()

Arama editor.destroy() düzenleyici DOM sarmalayıcısını kaldırmak ve orijinali geri yüklemek için <textarea> belgedeki konumuna. Bir görünümün bağlantısını keserken tek sayfalı uygulamalarda kullanışlıdır.

1
2
3
4

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

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

Değişikliklere tepki verme onChange

Geçmek onChange Her içerik değişikliğinde bilgilendirilmek için geri arama. Geçerli işaretleme dizesini alır.

1
2
3
4
5

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

Taslak otomatik kaydetme özelliği localStorage

Kullanmak onChange Her tuş vuruşunda bir taslak kaydetmek için. Düzenleyiciyi başlatmadan önce metin alanını önceden doldurarak geri yükleyin.

 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);
});

Form Gönderimi

Çünkü MarkdownEditor doğrudan yerel üzerinde oluşturulmuştur <textarea>, kutudan çıktığı anda her arka uç çerçevesiyle (Django, Laravel, PHP, Ruby on Rails, vb.) uyumludur.

"Önce Yerli" felsefesinin parladığı yer burasıdır. Formu göndermeden önce verileri manuel olarak senkronize etmeniz gerekmez. Tarayıcı, düzenleyiciye tam olarak standart bir giriş alanı gibi davranır.

 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>

Not: MarkdownEditor eklentisinin başlatılması zorunludur

Sadece standart bir HTML kullanın <form>. name textarea'daki özellik, sunucunuzun içeriği tanımlamak için kullanacağı özelliktir.

🚀 Neden Arka Uçlar İçin Oyunun Kurallarını Değiştiriyor?

Editör yereli koruduğu için <textarea> davranışı, sunucunuz verileri standart bir dize olarak işler. Sıfır ekstra mantık gerekli: hayır preventDefault() ve kılavuz yok FormData yapı.

💡 Bu neden bir "Öldürücü Özellik":

Çoğu düzenleyici (Quill, Editor.js, simpleMDE, easyMDE gibi) verileri karmaşık JSON yapılarında kaydeder. Bir geliştirici bunları kullanıyorsa, veritabanı şemasını ve oluşturma mantığını yeniden yazması gerekir.

MarkdownEditor ile bir geliştirici eski bir web sitesini alıp düz bir web sitesini değiştirebilir <textarea> editörünüzle çalışırsınız ve arka uç bunun değiştiğini bile bilmez. Her zaman aldığı ham metni alır ancak kullanıcı 10 kat daha iyi bir deneyim yaşar.

🖼️ Gelişmiş Resim Yükleme

Görüntü yüklemelerini yerel olarak yönetmek: Yavaş, bellek ağırlıklı Base64 dizelerine güvenmek yerine, hem performans hem de SEO açısından önemli bir kazançtır.

Yapıştır ve bırak

Bir ekran görüntüsünü yapıştırın veya bir görüntü dosyasını düzenleyiciye sürükleyin; araç çubuğu düğmesiyle aynı uç nokta üzerinden yüklenir. Düzenleyicinin hiçbir zaman donmuş görünmemesi için bir yer tutucu hemen görünür ve yükleme gerçekleştiğinde bunun yerini gerçek yol alır. Yükleme başarısız olursa yer tutucu, sessizce kaybolmak yerine görünür bir işaretleyiciyle değiştirilir.

Bu ihtiyaç uploadUrl aşağıda yapılandırılmıştır. Bu olmadan, bir resmin yapıştırılması hiçbir şey yapmaz ve editör, ne ekleneceğini açıklayan bir uyarıyı günlüğe kaydeder, çünkü alternatif, veritabanınızdaki bir Base64 dizesi olacaktır.

Aynı anda birden fazla dosya tek tek yüklenir, böylece görüntüler geldikleri sıraya göre iner.

Yapılandırma Seçenekleri

Görüntü aracı şunları destekler: fileInput doğrudan sunucu yüklemelerini yönetecek yapılandırma.

• accept: İzin verilen resim formatlarının bir dizisini tanımlayın (ör. 'webp', 'avif')
• uploadUrl: Arka uç uç noktasını belirtin. File nesne aracılığıyla gönderilecek POST
• params: Görüntü dosyasının yanında ek veriler (CSRF belirteçleri, kullanıcı kimlikleri veya klasör adları gibi) göndermek için isteğe bağlı nesne

Kullanım örneği (Tam Yapılandırma)

 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);

📡 Sunucu Entegrasyonu

Talep

Editör bir mesaj gönderir POST olarak talep et multipart/form-data. Varsayılan olarak şunları içerir:

• image_file: Gerçek dosya nesnesi
• image_alt: Kullanıcının girdiği alternatif metin
• ...artı şu şekilde tanımlanan tüm özel veriler: params nesne

Gerekli Yanıt

Başarılı bir yüklemeyi onaylamak ve görüntüyü düzenleyiciye eklemek için sunucunuzun aşağıdaki JSON yapısını ** döndürmesi gerekir**:

1
2
3
4

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

Not: Anahtarı kullandığınızdan emin olun image_path yüklenen görselin URL'si için.

Resim Alternatif Metin Doğrulaması (altInput)

İçeriğinizin erişilebilir ve SEO dostu kalmasını sağlamak için MarkdownEditor varsayılan olarak alternatif metin doğrulamasını zorunlu kılar.

• Varsayılan Davranış: Eğer altInput tanımlanmamıştır, varsayılan olarak { required: true }
• Erişilebilirliği Zorunlu Hale Getirin: Bir alternatif açıklama sağlanana kadar kullanıcıların resim eklemesi engellenecektir

1. Varsayılan (Yapılandırma gerekmez)

1
2
3
4

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

2. Kısayol (Doğrulamayı Devre Dışı Bırak)

Açıklamaları olmayan görsellere izin vermek istiyorsanız boole değerini şu şekilde ayarlamanız yeterlidir: false.

1
2
3

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

3. Nesne tabanlı (Açık)

1
2
3
4
5

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

Standart Görüntü Kullanımı (Hayır fileInput)

Eğer fileInput yapılandırılmamışsa, düzenleyici varsayılan olarak basit bir URL tabanlı modeli kullanır. Kullanıcılarınız çoğunlukla harici resim barındırıcılarına bağlantı veriyorsa bu idealdir.

1
2
3
4
5
6
7
8

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

💡 Param'ları neden kullanmalıyım?

Laravel veya Django gibi çerçevelerde CSRF belirteci olmadan dosya yükleyemezsiniz. Ekleyerek _token -e params isteğiniz, sunucu tarafı denetleyicileriniz için "Sıfır Mantık" felsefesini koruyarak arka ucun güvenlik ara yazılımından sorunsuz bir şekilde geçecektir.

⌨️ Klavye Kısayolları

Yaygın biçimlendirme eylemleri, araç çubuğuna dokunmadan doğrudan klavyeden tetiklenebilir. Her kısayol aynı zamanda karşılık gelen araç çubuğu düğmesinin araç ipucunda da gösterilir.

🔍 Bul ve Değiştir

Düzenleyicinin içinde yerleşik bir bul ve değiştir paneli mevcuttur: tarayıcı uzantısına veya ayrı bir araca gerek yoktur.

• Basmak Ctrl + F (veya ⌘ F) Bul panelini açmak için
• Basmak Ctrl + H (veya ⌘ H) Bul ve Değiştir panelini açmak için
• Arama büyük/küçük harfe duyarlı değildir ve canlı bir maç sayacı gösterir (ör. 3/12)
• ▲ / ▼ düğmeleriyle eşleşmelerde gezinin veya Enter / Shift + Enter
• Değiştir mevcut vurgulanan eşleşmenin yerine geçer; Tümünü Değiştir her tekrarı aynı anda değiştirir
• Basmak Escape paneli kapatmak ve odağı editöre döndürmek için

Panel, düzenleyici içerik alanının sağ üst köşesinde kayar ve yazmayı kesintiye uğratmaz.

🔗 Yapıştırılan bir URL'den bağlantılar

Bir metin seçin, üzerine bir URL yapıştırın ve seçtiğiniz şeyin yerine geçen URL yerine bir işaretleme bağlantısı elde edersiniz.

1
2

Read the docs                        <- select "the docs", paste https://example.com
Read [the docs](https://example.com) <- what you get

Kural kasıtlı olarak katıdır: yalnızca çıplak bir http veya https Boşluk içermeyen URL bu şekilde ele alınır. URL içeren bir cümleyi yapıştırmak veya hiçbir şey seçilmeden yapıştırmak sıradan bir yapıştırma gibi davranır.

Özellikler

Tam Yapılandırma Örneği

MarkdownEditor'ü özel araç çubuğu sıralaması ve gelişmiş resim yükleme işlemleri de dahil olmak üzere tüm temel özelliklerle başlatmak için bu kapsamlı örneği kullanın.

 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
34
35
36
37
38

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');
    },
    labels: {
        'Bold': 'Gras',
        'Italic': 'Italique',
        'Uploading...': 'Téléversement...',
    },
    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();