Docs Contribution Guide

Next.js Docs Katkı Kılavuzuna hoş geldiniz! Burada olmanızdan dolayı heyecanlıyız.

Bu sayfada Next.js belgelerinin nasıl düzenleneceğine ilişkin talimatlar yer almaktadır. Amacımız, topluluktaki herkesin dokümanlarımıza katkıda bulunma ve dokümanlarımızı geliştirme yetkisine sahip olmasını sağlamaktır.

Why Contribute?

Açık kaynak çalışmaları asla bitmez, dokümantasyon da öyle. Belgelere katkıda bulunmak, yeni başlayanların açık kaynağa dahil olması ve deneyimli geliştiricilerin bilgilerini toplulukla paylaşırken daha karmaşık konulara açıklık getirmesi için iyi bir yoldur.

Next.js dokümanlarına katkıda bulunarak, tüm geliştiriciler için daha sağlam bir öğrenme kaynağı oluşturmamıza yardımcı oluyorsunuz. İster bir yazım hatası, ister kafa karıştırıcı bir bölüm bulmuş olun, ister belirli bir konunun eksik olduğunu fark etmiş olun, katkılarınız memnuniyetle karşılanır ve takdir edilir.

How to Contribute

Dokümanların içeriği Next.js reposunda bulunabilir: . Katkıda bulunmak için dosyaları doğrudan GitHub'da düzenleyebilir veya depoyu klonlayıp dosyaları yerel olarak düzenleyebilirsiniz.

GitHub Workflow

GitHub'da yeniyseniz, bir depoyu nasıl çatallayacağınızı, bir dal oluşturacağınızı ve bir çekme isteği göndereceğinizi öğrenmek için GitHub Açık Kaynak Kılavuzu 'nu okumanızı öneririz.

Bilmekte fayda var: Temel doküman kodu, Next.js genel deposuyla senkronize edilen özel bir kod tabanında bulunur. Bu, dokümanları yerel olarak önizleyemeyeceğiniz anlamına gelir. Ancak, bir çekme isteğini birleştirdikten sonra nextjs.org adresinde değişikliklerinizi göreceksiniz.

Writing MDX

Dokümanlar, JSX sözdizimini destekleyen bir markdown formatı olan MDX ile yazılmıştır. Bu, dokümanlara React bileşenleri yerleştirmemize olanak tanır. Markdown sözdizimine hızlı bir genel bakış için GitHub Markdown Kılavuzu 'na bakın.

VSCode

Previewing Changes Locally

VSCode, düzenlemelerinizi yerel olarak görmek için kullanabileceğiniz yerleşik bir markdown önizleyicisine sahiptir. MDX dosyaları için önizleyiciyi etkinleştirmek için kullanıcı ayarlarınıza bir yapılandırma seçeneği eklemeniz gerekir.

Komut paletini açın (Mac'te⌘ + ⇧ + P veya Windows'ta Ctrl + Shift + P ) ve Preferences: Open User Settings (JSON) adresinden arama yapın.

Ardından, settings.json dosyanıza aşağıdaki satırı ekleyin:

settings.json
{
  "files.associations": {
    "*.mdx": "markdown"
  }
}

Ardından, komut paletini tekrar açın ve Markdown: Preview File veya Markdown: Open Preview to the Side adreslerini arayın. Bu, biçimlendirilmiş değişikliklerinizi görebileceğiniz bir önizleme penceresi açacaktır.

Extensions

VSCode kullanıcıları için aşağıdaki uzantıları da öneriyoruz:

Review Process

Katkınızı gönderdikten sonra Next.js veya Geliştirici Deneyimi ekipleri değişikliklerinizi inceleyecek, geri bildirimde bulunacak ve hazır olduğunda çekme isteğini birleştirecektir.

Herhangi bir sorunuz varsa veya PR yorumlarınızda daha fazla yardıma ihtiyacınız olursa lütfen bize bildirin. Next.js dokümanlarına katkıda bulunduğunuz ve topluluğumuzun bir parçası olduğunuz için teşekkür ederiz!

İpucu: PR'ınızı göndermeden önce Daha Güzel çalıştırmak için pnpm prettier-fix adresini çalıştırın.

File Structure

Dokümanlar dosya sistemi yönlendirmesi kullanır. Her klasör ve içindeki dosyalar /docs bir rota segmentini temsil eder. Bu segmentler URL yollarını, navigasyonu ve ekmek kırıntılarını oluşturmak için kullanılır.

Dosya yapısı sitede gördüğünüz navigasyonu yansıtır ve varsayılan olarak navigasyon öğeleri alfabetik olarak sıralanır. Ancak, klasör veya dosya adının önüne iki basamaklı bir sayı (00-) ekleyerek öğelerin sırasını değiştirebiliriz.

Örneğin, işlevler API Referansında sayfalar alfabetik olarak sıralanmıştır çünkü bu, geliştiricilerin belirli bir işlevi bulmasını kolaylaştırır:

03-functions
├── cookies.mdx
├── draft-mode.mdx
├── fetch.mdx
└── ...

Ancak, yönlendirme bölümünde, dosyaların önüne iki basamaklı bir sayı eklenir ve geliştiricilerin bu kavramları öğrenmesi gereken sıraya göre sıralanır:

02-routing
├── 01-defining-routes.mdx
├── 02-pages-and-layouts.mdx
├── 03-linking-and-navigating.mdx
└── ...

Bir sayfayı hızlı bir şekilde bulmak için, VSCode'daki arama çubuğunu açmak üzere ⌘ + P (Mac) veya Ctrl + P (Windows) adresini kullanabilirsiniz. Ardından, aradığınız sayfanın slug'ını yazın. Örn. defining-routes

Neden bir manifesto kullanmıyorsunuz?

Bir manifesto dosyası kullanmayı düşündük (doküman navigasyonunu oluşturmanın bir başka popüler yolu), ancak bir manifestonun dosyalarla hızla senkronize olmayacağını gördük. Dosya sistemi yönlendirmesi bizi dokümanların yapısı hakkında düşünmeye zorluyor ve Next.js için daha doğal hissettiriyor.

Metadata

Her sayfada, dosyanın üst kısmında üç çizgi ile ayrılmış bir meta veri bloğu bulunur.

Required Fields

Aşağıdaki alanlar zorunludur:

FieldDescription
titleThe page's <h1> title, used for SEO and OG Images.
descriptionThe page's description, used in the <meta name="description"> tag for SEO.
required-fields.mdx
---
title: Page Title
description: Page Description
---

Sayfa başlığını 2-3 kelimeyle (örn. Görüntüleri Optimize Etmek) ve açıklamayı 1-2 cümleyle (örn. Next.js'de görüntüleri nasıl optimize edeceğinizi öğrenin) sınırlamak iyi bir uygulamadır.

Optional Fields

Aşağıdaki alanlar isteğe bağlıdır:

FieldDescription
nav_titleOverrides the page's title in the navigation. This is useful when the page's title is too long to fit. If not provided, the title field is used.
sourcePulls content into a shared page. See Shared Pages.
relatedA list of related pages at the bottom of the document. These will automatically be turned into cards. See Related Links.
optional-fields.mdx
---
nav_title: Nav Item Title
source: app/building-your-application/optimizing/images
related:
  description: See the image component API reference.
  links:
    - app/api-reference/components/image
---

App and Pages Docs

App Router ve Pages Router 'daki özelliklerin çoğu tamamen farklı olduğundan, her biri için dokümanlar ayrı bölümlerde tutulmaktadır (02-app ve 03-pages). Bununla birlikte, aralarında paylaşılan birkaç özellik vardır.

Shared Pages

İçeriğin yinelenmesini ve içeriğin senkronize olmaması riskini önlemek için, içeriği bir sayfadan diğerine çekmek için source alanını kullanırız. Örneğin, <Link> bileşeni Uygulama ve Sayfalarda çoğunlukla aynı şekilde davranır. İçeriği çoğaltmak yerine, içeriği app/.../link.mdx adresinden pages/.../link.mdx adresine çekebiliriz:

app/.../link.mdx
---
title: <Link>
description: API reference for the <Link> component.
---
 
This API reference will help you understand how to use the props
and configuration options available for the Link Component.
pages/.../link.mdx
---
title: <Link>
description: API reference for the <Link> component.
source: app/api-reference/components/link
---
 
{/* DO NOT EDIT THIS PAGE. */}
{/* The content of this page is pulled from the source above. */}

Bu nedenle içeriği tek bir yerde düzenleyebilir ve her iki bölüme de yansıtabiliriz.

Shared Content

Paylaşılan sayfalarda, bazen App Rout er veya Pages Router 'a özgü içerik olabilir. Örneğin, <Link> bileşeninin yalnızca Pages 'da kullanılabilen ancak App'da kullanılamayan bir shallow prop'u vardır.

İçeriğin yalnızca doğru yönlendiricide gösterildiğinden emin olmak için, içerik bloklarını bir <AppOnly> veya <PagesOnly> bileşenlerine sarabiliriz:

app/.../link.mdx
This content is shared between App and Pages.
 
<PagesOnly>
 
This content will only be shown on the Pages docs.
 
</PagesOnly>
 
This content is shared between App and Pages.

Bu bileşenleri muhtemelen örnekler ve kod blokları için kullanacaksınız.

Code Blocks

Kod blokları kopyalanıp yapıştırılabilecek asgari bir çalışma örneği içermelidir. Bu, kodun herhangi bir ek yapılandırma olmadan çalışabilmesi gerektiği anlamına gelir.

Örneğin, <Link> bileşeninin nasıl kullanılacağını gösteriyorsanız, import deyimini ve <Link> bileşeninin kendisini eklemelisiniz.

app/page.tsx
import Link from 'next/link'
 
export default function Page() {
  return <Link href="/about">About</Link>
}

Örnekleri işlemeden önce her zaman yerel olarak çalıştırın. Bu, kodun güncel ve çalışır durumda olmasını sağlayacaktır.

Language and Filename

Kod blokları, dili ve filename adresini içeren bir başlığa sahip olmalıdır. Kullanıcıların komutu nereye gireceklerini yönlendirmeye yardımcı olan özel bir Terminal simgesi oluşturmak için bir filename prop ekleyin. Örneğin:

code-example.mdx
```bash filename="Terminal"
npx create-next-app
```

Dokümanlardaki örneklerin çoğu tsx ve jsx dillerinde ve birkaçı da bash dilinde yazılmıştır. Ancak, desteklenen herhangi bir dili kullanabilirsiniz, işte tam liste.

JavaScript kod bloklarını yazarken aşağıdaki dil ve uzantı kombinasyonlarını kullanırız.

LanguageExtension
JavaScript files with JSX code```jsx.js
JavaScript files without JSX```js.js
TypeScript files with JSX```tsx.tsx
TypeScript files without JSX```ts.ts

TS and JS Switcher

TypeScript ve JavaScript arasında geçiş yapmak için bir dil değiştirici ekleyin. Kod blokları önce TypeScript olmalı ve kullanıcılara uyum sağlamak için bir JavaScript sürümü bulunmalıdır.

Şu anda TS ve JS örneklerini birbiri ardına yazıyoruz ve bunları switcher prop ile ilişkilendiriyoruz:

code-example.mdx
```tsx filename="app/page.tsx" switcher
 
```
 
```jsx filename="app/page.js" switcher
 
```

Bilmekte fayda var: Gelecekte TypeScript parçacıklarını otomatik olarak JavaScript'e derlemeyi planlıyoruz. Bu arada, transform.tools adresini kullanabilirsiniz.

Line Highlighting

Kod satırları vurgulanabilir. Bu, kodun belirli bir bölümüne dikkat çekmek istediğinizde kullanışlıdır. highlight prop'una bir sayı girerek satırları vurgulayabilirsiniz.

Tek hat: highlight={1}

app/page.tsx
import Link from 'next/link'
 
export default function Page() {
  return <Link href="/about">About</Link>
}

Çoklu Hatlar: highlight={1,3}

app/page.tsx
import Link from 'next/link'
 
export default function Page() {
  return <Link href="/about">About</Link>
}

Hat Aralığı: highlight={1-5}

app/page.tsx
import Link from 'next/link'
 
export default function Page() {
  return <Link href="/about">About</Link>
}

Icons

Aşağıdaki simgeler dokümanlarda kullanılmak üzere mevcuttur:

mdx-icon.mdx
<Check size={18} />
<Cross size={18} />

Çıktı:

Dokümanlarda emoji kullanmıyoruz.

Notes

Önemli ancak kritik olmayan bilgiler için notları kullanın. Notlar, kullanıcının dikkatini ana içerikten uzaklaştırmadan bilgi eklemenin iyi bir yoludur.

notes.mdx
> **Good to know**: This is a single line note.
 
> **Good to know**:
>
> - We also use this format for multi-line notes.
> - There are sometimes multiple items worth knowing or keeping in mind.

Çıktı:

Bilmekte fayda var: Bu tek satırlık bir nottur.

Bildiğim iyi oldu:

  • Bu formatı çok satırlı notlar için de kullanırız.
  • Bazen bilinmesi veya akılda tutulması gereken birden fazla öğe vardır.

İlgili Bağlantılar, mantıksal sonraki adımlara bağlantılar ekleyerek kullanıcının öğrenme yolculuğuna rehberlik eder.

Sayfanın meta verilerindeki related alanını kullanarak ilgili bağlantıları oluşturun.

example.mdx
---
related:
  description: Learn how to quickly get started with your first application.
  links:
    - app/building-your-application/routing/defining-routes
    - app/building-your-application/data-fetching
    - app/api-reference/file-conventions/page
---

Nested Fields

FieldRequired?Description
titleOptionalThe title of the card list. Defaults to Next Steps.
descriptionOptionalThe description of the card list.
linksRequiredA list of links to other doc pages. Each list item should be a relative URL path (without a leading slash) e.g. app/api-reference/file-conventions/page

Diagrams

Diyagramlar karmaşık kavramları açıklamak için harika bir yoldur. Vercel'in tasarım kılavuzunu izleyerek diyagramlar oluşturmak için Figma kullanıyoruz.

Diyagramlar şu anda özel Next.js sitemizdeki bir /public klasöründe yer almaktadır. Bir diyagramı güncellemek veya eklemek isterseniz, lütfen fikirlerinizle birlikte bir GitHub sorunu açın.

Custom Components and HTML

Dokümanlar için kullanılabilen React Bileşenleri şunlardır: <Image /> (next/image), <PagesOnly />, <AppOnly />, <Cross /> ve <Check />. Dokümanlarda <details> etiketi dışında ham HTML'ye izin vermiyoruz.

Yeni bileşenler için fikirleriniz varsa, lütfen bir GitHub sorunu açın .

Style Guide

Bu bölüm, teknik yazarlığa yeni başlayanlar için doküman yazmaya yönelik yönergeler içerir.

Page Templates

Sayfalar için katı bir şablonumuz olmasa da, dokümanlarda tekrarlandığını göreceğiniz sayfa bölümleri vardır:

Gerektiğinde bu bölümleri eklemekten çekinmeyin.

Page Types

Doküman sayfaları da iki kategoriye ayrılmıştır: Kavramsal ve Referans.

Bilmekte fayda var: Katkıda bulunduğunuz sayfaya bağlı olarak, farklı bir ses ve stil izlemeniz gerekebilir. Örneğin, kavramsal sayfalar daha öğreticidir ve kullanıcıya hitap etmek için siz kelimesini kullanır. Referans sayfaları daha tekniktir, "oluştur, güncelle, kabul et" gibi daha zorunlu kelimeler kullanırlar ve siz kelimesini atlama eğilimindedirler.

Voice

Belgeler arasında tutarlı bir stil ve ses sağlamak için bazı yönergeler aşağıda verilmiştir:

Bu yönergeler kapsamlı olmamakla birlikte, başlamanıza yardımcı olacaktır. Teknik yazarlık konusunda daha derinlere inmek isterseniz Google Teknik Yazarlık Kursu'na göz atın: .

Belgelere katkıda bulunduğunuz ve Next.js topluluğunun bir parçası olduğunuz için teşekkür ederiz!