Mintlify Ignored This Feature Request for 6 Months. Here’s Our Solution.

Modern yazılım geliştirme dünyasında, kaliteli ve güncel dokümantasyon, başarılı bir ürünün olmazsa olmazıdır. Mintlify gibi platformlar, geliştiricilere şık ve kullanıcı dostu dokümantasyon siteleri oluşturma konusunda büyük kolaylıklar sunar. Ancak, ya kritik bir iş ihtiyacınız için gerekli olan temel bir özellik aylarca göz ardı edilirse? İşte tam da bu noktada, geliştirici ekibimizin karşılaştığı zorluğun hikayesi başlıyor. Bu makalede, altı ay boyunca Mintlify’dan yanıt alamadığımız bir özellik isteği karşısında nasıl kendi çözümümüzü geliştirdiğimizi, bu sürecin teknik detaylarını ve elde ettiğimiz sonuçları adım adım inceleyeceğiz. Bu yolculuk, sadece bir problemi çözmekle kalmayıp, aynı zamanda esneklik ve kontrolün gücünü keşfetmemizi sağladı.

Mintlify, teknik dokümantasyon oluşturma ve yayınlama süreçlerini basitleştirmeyi hedefleyen modern bir platform olarak, son zamanlarda geliştiriciler arasında oldukça popüler hale geldi. Birçok şirket, hızlı kurulumu, göz alıcı temaları, Markdown tabanlı içeriği kolayca yayınlama yeteneği ve entegre arama özellikleriyle Mintlify’ı tercih ediyor. Geliştiriciler, genellikle birkaç komutla sıfırdan profesyonel görünümlü bir dokümantasyon sitesi kurabilmenin ve içeriklerini GitHub üzerinden yönetebilmenin rahatlığını yaşıyorlar. Özellikle küçük ve orta ölçekli ekipler için, ürünlerini hızla pazara sürme veya geliştirici deneyimini artırma noktasında büyük bir zaman kazancı sağlıyor.

Ancak, her araç gibi Mintlify’ın da belirli sınırlılıkları mevcut. Genel kullanım senaryoları için harika olsa da, bazı niş veya gelişmiş ihtiyaçlar ortaya çıktığında esneklik konusunda zorluklar yaşanabiliyor. Bizim durumumuzda, dinamik veri kaynaklarından (örneğin, sürekli değişen bir ürün API’si veya bir veritabanı) otomatik olarak çekilen içeriğin dokümantasyona entegre edilmesi gerekiyordu. Mevcut Mintlify yapısı, statik Markdown dosyalarına dayalı olduğu için, bu tür dinamik içeriklerin güncel ve hatasız bir şekilde sunulması konusunda bizi çıkmaza soktu. Örneğin, X Şirketi’nin sunduğu çok sayıda mikroservis, her birinin kendi API tanımına ve kullanım kılavuzuna sahipti. Bu API’ler sık sık güncelleniyor, yeni uç noktalar ekleniyor veya mevcut olanlar değiştiriliyordu. Her bir güncelleme sonrası dokümantasyonu manuel olarak düzenlemek, hem zaman alıcı hem de hata yapmaya açık bir süreçti. İşte tam da bu noktada, Mintlify’ın “özel bir veri kaynağını doğrudan entegre etme ve bu verileri belirli şablonlar aracılığıyla otomatik olarak sayfalar halinde render etme” özelliği eksikliği, iş akışımızı ciddi şekilde aksatmaya başladı.

Buna ek olarak, bazı özel UI bileşenlerinin (örneğin, etkileşimli kod örnekleri, özel uyarı kutuları veya dinamik grafikler) kolayca entegre edilememesi de bir başka sınırlamayı teşkil ediyordu. Bizim için geliştirici deneyimi, sadece okunabilir bir metin sunmakla kalmıyor, aynı zamanda kullanıcıların kod örneklerini doğrudan denemelerine olanak tanıyan etkileşimli öğeleri de içeriyordu. Mintlify’ın sunduğu özelleştirme seçenekleri genel hatlarıyla yeterli olsa da, MDX (Markdown + JSX) benzeri bir yaklaşım sunarak içeriğin içine React bileşenleri gömmek gibi ileri düzey senaryolarda kısıtlı kalıyordu. Bu durum, dokümantasyonumuzu daha zengin ve işlevsel hale getirme çabalarımızı engelliyordu. Dolayısıyla, mevcut durum, ya Mintlify’ın sunduğuyla yetinmeyi ya da kendi ihtiyaçlarımıza uygun bir alternatif geliştirmeyi gerektiriyordu.

Aylarca Yanıtsız Kalan Özellik İsteği: Sabrın Sonu Nereye Varır?

Teknik dokümantasyon platformu Mintlify’ı aktif olarak kullandığımız dönemde, iş akışımız için kritik öneme sahip olduğunu düşündüğümüz bir özellik talebini ilettik. İsteğimiz, temelde, dinamik API verilerini doğrudan dokümantasyon içeriğimize entegre edebilme ve bu veriler üzerinden otomatik olarak güncellenen sayfalar oluşturabilme yeteneğiydi. Bu, özellikle sürekli değişen ürün veya hizmetler için dokümantasyonun manuel güncellemelerden kaynaklanan hatalarını ve gecikmelerini ortadan kaldıracaktı. Beklentimiz, bir Headless CMS’den veya doğrudan bir API uç noktasından çekilen verilerin, belirli Markdown şablonlarına göre otomatik olarak işlenerek dokümantasyon sayfalarına dönüştürülmesiydi. Bu sayede, ürünlerimizdeki değişiklikler anında dokümantasyona yansıyacak, geliştirici ekiplerimizin üzerindeki yük azalacak ve her zaman güncel bilgi sunulabilecekti.

Bu isteği ilk olarak Mintlify’ın resmi destek kanalları üzerinden, ardından GitHub issue’ları aracılığıyla ve son olarak da topluluk forumlarında dile getirdik. Her seferinde, isteğimizin değerlendirmeye alındığına dair otomatik yanıtlar aldık veya belirsiz bir “yol haritasına eklendi” mesajıyla karşılaştık. İlk birkaç hafta umutluyduk; sonuçta her geliştirme ekibi kendi önceliklerine sahiptir ve hemen aksiyon alınamayabilir. Ancak, haftalar ayları kovaladığında ve altı ay gibi uzun bir süre geçmesine rağmen ne somut bir geri bildirim ne de herhangi bir gelişme gözlemleyebildik. Bu durum, projemizin ilerleyişi üzerinde ciddi bir baskı oluşturmaya başladı. Dokümantasyon süreçlerimiz aksıyor, manuel müdahaleler nedeniyle hatalar artıyor ve geliştirici ekibimizin değerli zamanı verimsiz işlere harcanıyordu. Bu gecikmeler, sadece şirket içinde değil, aynı zamanda müşterilerimiz ve iş ortaklarımız nezdinde de bilgiye erişim sorunlarına yol açıyordu.

Mintlify’ın bu önemli talebimizi göz ardı etmesi veya önceliklendirememesi karşısında, sabrımız tükendi. Mevcut alternatifleri değerlendirdik; ancak hiçbir hazır çözüm, bizim spesifik ve entegre ihtiyaçlarımızı tam olarak karşılamıyordu. Bir yandan zaman kısıtlamaları, diğer yandan da projemizin doğası gereği bu dinamik dokümantasyon özelliğinin vazgeçilmez olması, bizi kendi çözümümüzü geliştirmeye itti. Bu karar, sadece bir özellik eksikliğini gidermekle kalmayacak, aynı zamanda dokümantasyon süreçlerimiz üzerinde tam kontrol sahibi olmamızı sağlayacaktı. Kendi çözümümüzü oluşturmak, ilk başta daha fazla emek ve kaynak gerektirse de, uzun vadede esneklik, sürdürülebilirlik ve bağımsızlık açısından çok daha değerli olacağına karar verdik. Bu, bir nevi “kendi kaderimizi kendimiz tayin etme” anıydı ve biz de bu kararı büyük bir motivasyonla hayata geçirmeye koyulduk.

Kendi Çözümümüzü Geliştirme Yolculuğu: Hangi Adımları İzledik?

Mintlify’ın pasif kalması üzerine, kendi dinamik dokümantasyon platformumuzu oluşturma kararı aldık. Bu yolculuk, dikkatli bir planlama ve aşamalı bir yaklaşımla şekillendi. Amacımız, sadece kayıp bir özelliği yerine koymak değil, aynı zamanda mevcut kısıtlamaları aşan, tamamen özelleştirilebilir ve geleceğe dönük bir çözüm inşa etmekti. İlk olarak, mevcut tüm ihtiyaçlarımızı ve gelecekteki potansiyel gereksinimlerimizi kapsayan detaylı bir analiz gerçekleştirdik. Bu süreçte, projenin kapsamını belirledik, kullanılacak teknolojileri seçtik ve mimari tasarım üzerinde yoğunlaştık. Her bir adım, hem teknik ekibimizin yetkinliklerini en üst düzeyde kullanmayı hem de projenin hedeflerine ulaşmasını sağlamayı amaçlıyordu.

Adım 1: İhtiyaç Analizi ve Mimari Tasarım

Projenin başlangıcında, iş birimlerimizden ve geliştirici ekiplerimizden gelen tüm geri bildirimleri topladık. Temel gereksinimler arasında dinamik API verilerini çekebilme, bu verileri görsel olarak zenginleştiren özel React/MDX bileşenleri kullanabilme, dokümantasyonun birden fazla versiyonunu yönetebilme ve CI/CD süreçleriyle otomatik yayınlama yeteneği bulunuyordu. Mimari tasarım için, Next.js’in statik site oluşturma (SSG) yeteneklerinden faydalanmaya karar verdik. Bu, hem hızlı yükleme süreleri hem de SEO dostu bir yapı sunacaktı. İçerik yönetimi için Headless CMS (örneğin Strapi veya Sanity.io) kullanma fikri ortaya çıktı, böylece teknik olmayan kullanıcılar da içerikleri kolayca yönetebilecekti. Verilerin alınması için basit bir GraphQL veya REST API katmanı oluşturulması planlandı. Bu aşama, projenin sağlam temellerini atmak ve gelecekteki genişlemeler için esnek bir yapı kurmak açısından hayati önem taşıyordu.

Adım 2: Çekirdek Yapının İnşası ve Dinamik İçerik Entegrasyonu

Mimari onaylandıktan sonra, Next.js tabanlı dokümantasyon uygulamasının çekirdeğini inşa etmeye başladık. Markdown ve MDX entegrasyonu için next-mdx-remote gibi kütüphaneleri kullandık. Bu sayede, Markdown dosyalarının içine doğrudan React bileşenleri gömebildik ve içeriklerimizi çok daha etkileşimli hale getirdik. Dinamik içerik entegrasyonu için, Next.js’in getStaticProps ve getStaticPaths fonksiyonlarını kullanarak API’lerden veri çekme mekanizmalarını kurduk. Örneğin, ürün özellik listelerini veya API uç nokta tanımlarını bir harici API’den çekip, bunları otomatik olarak dokümantasyon sayfalarına dönüştüren bir yapı oluşturduk. Aşağıda, basit bir API verisini çekip MDX içeriğine aktaran bir kod örneği bulunmaktadır:

// pages/docs/[slug].js
import { serialize } from 'next-mdx-remote/serialize';
import { MDXRemote } from 'next-mdx-remote';

// Özel React bileşenleri
const components = {
  Alert: ({ children }) => 
{children}
,
};

export default function Post({ source }) {
  return ;
}

export async function getStaticProps({ params }) {
  // Örnek: Dinamik veri çekme
  const res = await fetch(https://api.example.com/docs/${params.slug});
  const { content, dynamicData } = await res.json();

  // MDX içeriğine dinamik veriyi gömme
  const mdxSource = await serialize(content, { scope: { dynamicData } });

  return {
    props: {
      source: mdxSource,
    },
  };
}

export async function getStaticPaths() {
  // Örnek: Tüm doküman slug'larını çekme
  const res = await fetch('https://api.example.com/docs/slugs');
  const slugs = await res.json();

  const paths = slugs.map((slug) => ({ params: { slug } }));

  return { paths, fallback: false };
}
    

Bu kod bloğu sayesinde, her bir dokümantasyon sayfası için statik olarak önceden oluşturulmuş HTML dosyaları elde ederken, aynı zamanda bu sayfaların içeriğine dinamik verileri entegre edebildik. İçerik güncellendiğinde veya yeni API verileri geldiğinde, build süreci yeniden tetiklenerek dokümantasyonun otomatik olarak güncellenmesi sağlandı.

Adım 3: Otomatik Yayınlama ve CI/CD Entegrasyonu

Geliştirdiğimiz çözümün en güçlü yanlarından biri, otomatik yayınlama yeteneğiydi. Dokümantasyon içeriğimizin veya bağlı API'lerimizin güncellenmesi durumunda, manuel müdahale olmaksızın platformun otomatik olarak yeniden derlenip yayınlanmasını sağlamak için CI/CD (Sürekli Entegrasyon/Sürekli Dağıtım) boru hatları kurduk. GitHub Actions kullanarak, ana branşa yapılan her bir birleşme (merge) veya belirlenmiş bir API'nin güncellenmesi gibi olaylarda, dokümantasyonun otomatik olarak yeniden oluşturulmasını ve Vercel veya Netlify gibi bir CDN'e dağıtılmasını tetikledik. Bu, dokümantasyonumuzun her zaman en güncel bilgiyi yansıtmasını garanti altına aldı ve geliştirici ekibimizin manuel yayınlama yükünü ortadan kaldırdı. Basit bir GitHub Actions yapılandırması aşağıda gösterilmiştir:

# .github/workflows/deploy.yml
name: Dokümantasyon Dağıtımı

on:
  push:
    branches:
      - main
  # API güncellemelerini tetiklemek için web kancası da eklenebilir

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Kodları Çek
        uses: actions/checkout@v2

      - name: Node.js Kurulumu
        uses: actions/setup-node@v2
        with:
          node-version: '16'

      - name: Bağımlılıkları Yükle
        run: npm install

      - name: Dokümantasyonu Oluştur (Next.js Build)
        run: npm run build

      - name: Vercel'e Dağıt
        uses: amondnet/vercel-action@v20
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          # prod değişkeni, ana branşta her zaman production ortamına dağıtımı sağlar
          vercel-scope: 'production'
    

Bu otomasyon sayesinde, içerik yöneticileri Headless CMS üzerinden veya geliştiriciler API tanımında bir değişiklik yaptığında, dokümantasyon platformumuz hızlı ve güvenilir bir şekilde güncellenerek yeni bilgileri anında kullanıcılara sunar. Bu tam otomasyon, yalnızca zaman tasarrufu sağlamakla kalmadı, aynı zamanda dokümantasyonun kalitesini ve tutarlılığını da önemli ölçüde artırdı.

Çözümümüzün Teknik Detayları ve Uygulamalı Örnekler

Geliştirdiğimiz dokümantasyon platformu, sadece bir özellik eksikliğini gidermekle kalmayıp, aynı zamanda esneklik ve gelişmiş işlevsellik sunan bir yapıya büründü. Çözümümüz, Next.js'in gücüyle MDX (Markdown + JSX) entegrasyonunu birleştirerek, statik dokümantasyonun sınırlılıklarını aşmayı hedefledi. Bu bölümde, çözümümüzün en önemli teknik detaylarını ve gerçek dünya senaryolarında nasıl uygulandığını inceleyeceğiz. Özellikle özel Markdown/MDX bileşenleri oluşturma, API verilerini doğrudan dokümantasyona entegre etme ve mobil cihazlarda kusursuz bir deneyim sunma konularına odaklanacağız.

Özel Markdown/MDX Bileşenleri Nasıl Oluşturulur?

Mintlify gibi platformlar genellikle belirli bir dizi önceden tanımlanmış bileşenle gelir. Ancak, bizim ihtiyacımız, dokümantasyon içeriğimize özgü, markamıza uygun veya daha etkileşimli öğeler ekleyebilmekti. MDX sayesinde, Markdown dosyalarımızın içine doğrudan React bileşenleri yazabildik. Bu, örneğin, özel bir "Uyarı" kutusu, bir "Kodu Kopyala" düğmesi içeren bir kod bloğu veya dinamik olarak güncellenen bir ürün tablosu gibi bileşenler oluşturmamıza olanak tanıdı. Aşağıda, basit bir uyarı kutusu bileşeni (Alert) ve bunun MDX içinde nasıl kullanıldığına dair bir örnek bulunmaktadır:

// components/Alert.js
import React from 'react';

const Alert = ({ children, type = 'info' }) => {
  const getStyles = () => {
    switch (type) {
      case 'warning':
        return { backgroundColor: '#fffbe6', borderLeft: '4px solid #ffe58f' };
      case 'error':
        return { backgroundColor: '#fff1f0', borderLeft: '4px solid #ffccc7' };
      case 'success':
        return { backgroundColor: '#f6ffed', borderLeft: '4px solid #b7eb8f' };
      case 'info':
      default:
        return { backgroundColor: '#e6f7ff', borderLeft: '4px solid #91d5ff' };
    }
  };

  return (
    

      {children}
    
  );
};

export default Alert;
    

Bu bileşeni MDX içeriğimizde kullanmak için:

// example-doc.mdx
import Alert from '../components/Alert';

# Yeni Özellikler Duyurusu


  Bu özellik, son güncelleme ile birlikte kullanıma sunulmuştur.



  Lütfen bu özelliği kullanmadan önce uyumluluk belgelerini kontrol edin.

    

Bu yaklaşım, dokümantasyon yazarlarının içeriği zenginleştirmek için standart Markdown'ın ötesine geçmesine olanak tanır ve geliştiricilere, kullanıcı deneyimini iyileştiren özel UI öğeleri oluşturma konusunda tam kontrol sağlar. Görsel olarak, bu uyarı kutuları standart metin bloklarından ayrılarak okuyucunun dikkatini önemli bilgilere çekmeye yardımcı olur.

API Verilerini Dokümantasyona Nasıl Entegre Ederiz?

Dinamik içerik entegrasyonu, Mintlify'da eksikliğini hissettiğimiz en kritik özellikti. Kendi çözümümüzle, bu sorunu Next.js'in statik oluşturma (SSG) ve sunucu tarafı oluşturma (SSR) yeteneklerini kullanarak aştık. Örneğin, bir ürün API'sinden çekilen özellikleri veya hizmet durumlarını doğrudan dokümantasyon sayfalarımıza entegre edebiliriz. Bu, özellikle hızla gelişen ürünler için manuel güncellemelerin önüne geçerek, her zaman güncel bir dokümantasyon sunulmasını sağlar.

Örnek senaryo: Bir ürün API'sinden çekilen dinamik bir özellik listesini bir tablo olarak dokümantasyonda göstermek. İlk olarak, Next.js'in getStaticProps fonksiyonunda API çağrısı yaparız:

// pages/features.js
import { serialize } from 'next-mdx-remote/serialize';
import { MDXRemote } from 'next-mdx-remote';

const FeatureTable = ({ features }) => (
  
      {features.map((feature) => (
        
      ))}
    

    

      

        
Özellik Adı
        
Açıklama
        
Durum
      
    
    

          
{feature.name}
          
{feature.description}
          
{feature.status}
        
  
);

const components = { FeatureTable }; // MDX'te kullanılacak özel bileşen

export default function FeaturesPage({ source }) {
  return ;
}

export async function getStaticProps() {
  const res = await fetch('https://api.example.com/product-features');
  const features = await res.json(); // API'den gelen dinamik özellikler

  // MDX içeriği, dinamik veriyi kullanmak için özel bir bileşen çağırıyor
  const mdxContent = # Ürün Özellikleri

;

  const mdxSource = await serialize(mdxContent, { scope: { dynamicFeatures: features } });

  return {
    props: {
      source: mdxSource,
    },
    revalidate: 60, // 60 saniyede bir veriyi tekrar çekip sayfayı oluştur
  };
}
    

Bu örnekte, FeatureTable adında bir React bileşeni oluşturarak API'den gelen verileri doğrudan MDX içeriğine aktarıyoruz. revalidate: 60 parametresi sayesinde, sayfa her 60 saniyede bir arka planda yeniden oluşturularak en güncel verilerle yayınlanır. Bu, hem performans hem de veri tutarlılığı açısından oldukça etkili bir yöntemdir.

Mobilde Kusursuz Deneyim İçin Ne Yapmalıyız?

Günümüzde kullanıcıların büyük çoğunluğu dokümantasyonlara mobil cihazlar üzerinden eriştiği için, mobil uyumluluk vazgeçilmez bir gerekliliktir. Kendi çözümümüzü geliştirirken, responsive tasarım prensiplerini baştan sona uyguladık. Flexbox ve CSS Grid gibi modern CSS yaklaşımlarını kullanarak sayfa düzenimizi her ekran boyutuna adapte ettik. Küçük ekranlarda navigasyon menüsünün hamburger menüye dönüşmesi, içerik sütunlarının tek sütuna inmesi ve yazı tiplerinin boyutlarının otomatik olarak ayarlanması gibi özellikler standart olarak uygulandı. İşte basit bir media query örneği:

/* styles/globals.css */
.container {
  padding: 1rem;
}

.sidebar {
  width: 250px;
  float: left;
}

.main-content {
  margin-left: 270px;
}

@media (max-width: 768px) {
  .sidebar {
    width: 100%;
    float: none;
    order: -1; /* Mobil görünümde menüyü üste taşı */
  }

  .main-content {
    margin-left: 0;
    width: 100%;
  }

  /* Örneğin, hamburger menü görünür hale getirilebilir */
  .mobile-menu-toggle {
    display: block;
  }
}
    

Bu tür medya sorguları, dokümantasyonun farklı cihazlarda estetik ve işlevsel kalmasını sağlar. Ayrıca, mobil performansı artırmak için resim optimizasyonu (WebP formatı, sıkıştırma), lazy loading ve önbellekleme stratejileri de uygulandı. Bu detaylar, dokümantasyon platformumuzun her kullanıcıya, kullandığı cihazdan bağımsız olarak, sorunsuz bir deneyim sunmasını garantiledi.

İleri Düzey Kullanım İpuçları ve Performans Optimizasyonu

Kendi dokümantasyon çözümümüzü geliştirme sürecinde, sadece temel ihtiyaçları karşılamakla kalmayıp, aynı zamanda deneyimli kullanıcılar için de ileri düzey özellikler ve performans iyileştirmeleri sunmayı hedefledik. Bu kısım, mevcut platformunuzu daha da güçlendirecek ve kullanıcı deneyimini zirveye taşıyacak ipuçları ve püf noktalarını içermektedir. Unutmayın, iyi bir dokümantasyon platformu sadece bilgiyi sunmakla kalmaz, aynı zamanda bu bilgiyi hızlı, erişilebilir ve etkili bir şekilde sunar.

Gelişmiş Tema Özelleştirmeleri: Kendi çözümümüzün en büyük avantajlarından biri, tasarıma tam kontrol sağlamasıdır. CSS değişkenleri, Tailwind CSS gibi yardımcı araçlar veya doğrudan SCSS/Less gibi ön işlemciler kullanarak, markanızın kurumsal kimliğine tamamen uygun, benzersiz bir görünüm yaratabilirsiniz. Örneğin, tema renklerini, yazı tiplerini, gölgeleri veya düğme stillerini global olarak tanımlayarak, dokümantasyonunuzun her yerinde tutarlı bir estetik sağlayabilirsiniz. Dark mode (karanlık mod) desteğini entegre etmek de, özellikle uzun süreli okumalar için kullanıcı deneyimini önemli ölçüde iyileştiren bir özelliktir.

SEO İpuçları ve Yapısal Veri İşaretleme: Dokümantasyonunuzun arama motorlarında iyi sıralanması, kullanıcıların doğru bilgiye ulaşması için kritik öneme sahiptir. Next.js gibi bir çerçeve kullanırken, her sayfa için dinamik olarak