Markdown and MDX

Markdown metni biçimlendirmek için kullanılan hafif bir biçimlendirme dilidir. Düz metin sözdizimi kullanarak yazmanıza ve yapısal olarak geçerli HTML'ye dönüştürmenize olanak tanır. Genellikle web sitelerinde ve bloglarda içerik yazmak için kullanılır.

Sen yazıyorsun.

I **love** using [Next.js](https://nextjs.org/)

Çıktı:

<p>I <strong>love</strong> using <a href="https://nextjs.org/">Next.js</a></p>

MDX, doğrudan markdown dosyalarınıza JSX yazmanıza olanak tanıyan bir markdown üst kümesidir. Dinamik etkileşim eklemenin ve içeriğinize React bileşenleri yerleştirmenin güçlü bir yoludur.

Next.js, hem uygulamanızın içindeki yerel MDX içeriğini hem de sunucudan dinamik olarak getirilen uzak MDX dosyalarını destekleyebilir. Next.js eklentisi, Sunucu Bileşenlerinde (App Router'da varsayılan) kullanım desteği de dahil olmak üzere markdown ve React bileşenlerini HTML'ye dönüştürmeyi yönetir.

@next/mdx

@next/mdx paketi Next.js'yi markdown ve MDX işleyebilecek şekilde yapılandırmak için kullanılır. Verileri yerel dosyalardan alır ve doğrudan /pages veya /app dizininizde .mdx uzantılı sayfalar oluşturmanıza olanak tanır.

Next.js ile MDX'in nasıl yapılandırılacağını ve kullanılacağını inceleyelim.

Getting Started

MDX oluşturmak için gereken paketleri yükleyin:

npm install @next/mdx @mdx-js/loader @mdx-js/react @types/mdx

Uygulamanızın kök dizininde bir mdx-components.tsx dosyası oluşturun (src/ veya app/'nin üst klasörü):

Bilmenizde fayda var: mdx-components.tsx MDX'i App Router ile kullanmak için gereklidir ve onsuz çalışmaz.

import type { MDXComponents } from 'mdx/types'
 
export function useMDXComponents(components: MDXComponents): MDXComponents {
  return {
    ...components,
  }
}

MDX kullanacak şekilde yapılandırmak için projenizin kök dizinindeki next.config.js dosyasını güncelleyin:

const withMDX = require('@next/mdx')()
 
/** @type {import('next').NextConfig} */
const nextConfig = {
  // Configure `pageExtensions` to include MDX files
  pageExtensions: ['js', 'jsx', 'mdx', 'ts', 'tsx'],
  // Optionally, add any other Next.js config below
}
 
module.exports = withMDX(nextConfig)

Ardından, /app dizini içinde yeni bir MDX sayfası oluşturun:

  your-project
  ├── app
  │   └── my-mdx-page
  │       └── page.mdx
  └── package.json

Artık markdown kullanabilir ve React bileşenlerini doğrudan MDX sayfanızın içine aktarabilirsiniz:

import { MyComponent } from 'my-components'
 
# Welcome to my MDX page!
 
This is some **bold** and _italics_ text.
 
This is a list in markdown:
 
- One
- Two
- Three
 
Checkout my React component:
 
<MyComponent />

/my-mdx-page rotasına gittiğinizde işlenmiş MDX'iniz görüntülenmelidir.

Remote MDX

Markdown veya MDX dosyalarınız veya içeriğiniz başka bir yerde bulunuyorsa, bunları sunucudan dinamik olarak getirebilirsiniz. Bu, ayrı bir yerel klasörde, CMS'de, veritabanında veya başka herhangi bir yerde depolanan içerik için kullanışlıdır. Bu kullanım için popüler bir topluluk paketi next-mdx-remote.

Bilmekte fayda var: Lütfen dikkatli olun. MDX, JavaScript olarak derlenir ve sunucuda yürütülür. MDX içeriğini yalnızca güvenilir bir kaynaktan almalısınız, aksi takdirde bu durum uzaktan kod yürütülmesine (RCE) yol açabilir.

Aşağıdaki örnek next-mdx-remote adresini kullanmaktadır:

import { MDXRemote } from 'next-mdx-remote/rsc'
 
export default async function RemoteMdxPage() {
  // MDX text - can be from a local file, database, CMS, fetch, anywhere...
  const res = await fetch('https://...')
  const markdown = await res.text()
  return <MDXRemote source={markdown} />
}

/my-mdx-page-remote rotasına gittiğinizde işlenmiş MDX'iniz görüntülenmelidir.

Layouts

Bir düzeni MDX sayfaları arasında paylaşmak için Uygulama Yönlendiricisi ile yerleşik düzen desteğini kullanabilirsiniz.

export default function MdxLayout({ children }: { children: React.ReactNode }) {
  // Create any shared layout or styles here
  return <div style={{ color: 'blue' }}>{children}</div>
}

Remark and Rehype Plugins

MDX içeriğini dönüştürmek için isteğe bağlı olarak remark ve rehype eklentileri sağlayabilirsiniz.

Örneğin, GitHub Flavored Markdown'u desteklemek için remark-gfm adresini kullanabilirsiniz.

remark ve rehype ekosistemi yalnızca ESM olduğundan, yapılandırma dosyası olarak next.config.mjs kullanmanız gerekecektir.

import remarkGfm from 'remark-gfm'
import createMDX from '@next/mdx'
 
/** @type {import('next').NextConfig} */
const nextConfig = {
  // Configure `pageExtensions`` to include MDX files
  pageExtensions: ['js', 'jsx', 'mdx', 'ts', 'tsx'],
  // Optionally, add any other Next.js config below
}
 
const withMDX = createMDX({
  // Add markdown plugins here, as desired
  options: {
    remarkPlugins: [remarkGfm],
    rehypePlugins: [],
  },
})
 
// Merge MDX config with Next.js config
export default withMDX(nextConfig)

Frontmatter

Frontmatter, bir sayfa hakkındaki verileri depolamak için kullanılabilen YAML benzeri bir anahtar/değer eşleştirmesidir. @next/mdx varsayılan olarak frontmatter'ı desteklemez, ancak MDX içeriğinize frontmatter eklemek için birçok çözüm vardır, örneğin:

• remark-frontmatter
• remark-mdx-frontmatter
• gri madde.

Sayfa meta verilerine @next/mdx ile erişmek için .mdx dosyası içinden bir meta veri nesnesini dışa aktarabilirsiniz:

export const metadata = {
  author: 'John Doe',
}
 
# My MDX page

Custom Elements

Markdown kullanmanın hoş yönlerinden biri, yerel HTML öğeleriyle eşleşmesi, yazmayı hızlı ve sezgisel hale getirmesidir:

This is a list in markdown:
 
- One
- Two
- Three

Yukarıdakiler aşağıdaki HTML adresini oluşturur:

<p>This is a list in markdown:</p>
 
<ul>
  <li>One</li>
  <li>Two</li>
  <li>Three</li>
</ul>

Web sitenize veya uygulamanıza özel bir his vermek için kendi öğelerinizi şekillendirmek istediğinizde, kısa kodları iletebilirsiniz. Bunlar, HTML öğeleriyle eşleşen kendi özel bileşenlerinizdir.

Bunu yapmak için, uygulamanızın kök dizinindeki mdx-components.tsx dosyasını açın ve özel öğeler ekleyin:

import type { MDXComponents } from 'mdx/types'
import Image, { ImageProps } from 'next/image'
 
// This file allows you to provide custom React components
// to be used in MDX files. You can import and use any
// React component you want, including inline styles,
// components from other libraries, and more.
 
export function useMDXComponents(components: MDXComponents): MDXComponents {
  return {
    // Allows customizing built-in components, e.g. to add styling.
    h1: ({ children }) => <h1 style={{ fontSize: '100px' }}>{children}</h1>,
    img: (props) => (
      <Image
        sizes="100vw"
        style={{ width: '100%', height: 'auto' }}
        {...(props as ImageProps)}
      />
    ),
    ...components,
  }
}

Deep Dive: How do you transform markdown into HTML?

React markdown'ı yerel olarak anlamaz. Markdown düz metninin önce HTML'ye dönüştürülmesi gerekir. Bu remark ve rehype ile gerçekleştirilebilir.

remark markdown etrafında bir araç ekosistemidir. rehype aynıdır, ancak HTML içindir. Örneğin, aşağıdaki kod parçacığı markdown'u HTML'ye dönüştürür:

import { unified } from 'unified'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import rehypeSanitize from 'rehype-sanitize'
import rehypeStringify from 'rehype-stringify'
 
main()
 
async function main() {
  const file = await unified()
    .use(remarkParse) // Convert into markdown AST
    .use(remarkRehype) // Transform to HTML AST
    .use(rehypeSanitize) // Sanitize HTML input
    .use(rehypeStringify) // Convert AST into serialized HTML
    .process('Hello, Next.js!')
 
  console.log(String(file)) // <p>Hello, Next.js!</p>
}

remark ve rehype ekosistemi, sözdizimi vurgulama, başlıkları bağlama, içindekiler tablosu oluşturma ve daha fazlası için eklentiler içerir.

Yukarıda gösterildiği gibi @next/mdx kullanırken, sizin için halledildiği için doğrudan remark veya rehype kullanmanıza gerek yoktur. Burada, @next/mdx paketinin altında ne yaptığının daha iyi anlaşılması için açıklıyoruz.

Using the Rust-based MDX compiler (Experimental)

Next.js, Rust dilinde yazılmış yeni bir MDX derleyicisini desteklemektedir. Bu derleyici hala deneyseldir ve üretim kullanımı için önerilmez. Yeni derleyiciyi kullanmak için, withMDX adresine ilettiğinizde next.config.js adresini yapılandırmanız gerekir:

module.exports = withMDX({
  experimental: {
    mdxRs: true,
  },
})

Helpful Links

• MDX
• @next/mdx
• Açıklama
• rehype
• Markdoc