Mintlify, dokumentacja czytelna dla ludzi i modeli

Mintlify, dokumentacja czytelna dla ludzi i modeli

Mintlify to hostowana platforma do dokumentacji technicznej. Piszesz pliki MDX w repozytorium, a w zamian dostajesz stronę z wyszukiwaniem, interaktywnym podglądem API i zestawem wyjść przeznaczonych dla asystentów kodu. Silnik jest zamknięty i objęty licencją Elastic 2.0, narzędzie wiersza poleceń ma wersję 4.2.816, a plan darmowy nazywa się Starter i daje pięć miejsc edytorskich.

Co Mintlify właściwie robi

Model pracy jest prosty i tym różni się od klasycznych generatorów statycznych: repozytorium z treścią jest źródłem prawdy, a budowanie i hosting należą do dostawcy. W katalogu leżą pliki .md albo .mdx, jeden plik docs.json z konfiguracją i opcjonalnie specyfikacje OpenAPI. Po podłączeniu repozytorium każdy scalony commit uruchamia wdrożenie po stronie Mintlify.

Strony mogą być zwykłym Markdownem, ale MDX otwiera dostęp do komponentów, których w czystym Markdownie nie ma: kart, akordeonów, ramek, pól opisujących odpowiedzi API. Dokumentacja wprost sugeruje, żeby migrację z innej platformy zacząć od plików .md, a dopiero potem przechodzić na MDX, kiedy treść już działa.

Druga noga to referencja API. Wskazujesz plik OpenAPI albo AsyncAPI, a platforma generuje z niego strony metod razem z podglądem, w którym czytelnik wysyła zapytanie prosto z przeglądarki. Podgląd API jest dostępny już w planie Starter, podobnie jak własna domena, edytor w przeglądarce, uwierzytelnianie i hostowany serwer MCP.

Trzecia noga, i to ona jest w tej kolekcji najciekawsza, to zestaw wyjść dla modeli językowych. Mintlify hostuje plik llms.txt, plik llms-full.txt, wersję Markdown każdej strony pod tym samym adresem z dopiskiem .md, serwer MCP nad treścią oraz menu kontekstowe pozwalające otworzyć bieżącą stronę w wybranym asystencie.

Czego Mintlify nie robi, też trzeba powiedzieć wprost. Nie jest silnikiem, który uruchomisz na własnym serwerze w wersji darmowej. Nie jest systemem zarządzania treścią dla redakcji nietechnicznej, choć edytor w przeglądarce zbliża go do tego. Nie zastąpi bloga ani strony marketingowej, bo cały układ jest zbudowany pod nawigację po dokumentacji. Nie sprawdzi też za Ciebie, czy opisane w tekście zachowanie zgadza się z kodem, bo strony i biblioteka żyją w oddzielnych repozytoriach i nic ich automatycznie nie wiąże.

Wersja, licencja i puste miejsce na GitHubie

Pakiet mint w rejestrze npm ma wersję 4.2.816. Jest cienkim opakowaniem: deklaruje dokładnie jedną zależność, @mintlify/cli w wersji 4.0.1419, a pole engines wymaga Node w wersji co najmniej 18. Pakiet mintlify publikowany jest równolegle pod tym samym numerem i zawiera to samo narzędzie.

Licencja to miejsce, w którym trzy źródła powinny się zgadzać, a jedno z nich po prostu nie istnieje. Pole license w rejestrze npm ma wartość Elastic-2.0. Rozpakowana paczka zawiera plik LICENSE z pełnym tekstem Elastic License 2.0 i notą praw autorskich Mintlify, Inc. z 2022 roku. Trzecie źródło, czyli plik licencyjny w repozytorium, sprawdzić się nie da: pole repository w manifeście wskazuje na github.com/mintlify/mint, a interfejs programistyczny GitHuba odpowiada dla tego adresu komunikatem o braku zasobu. Kod silnika nie jest publiczny.

To rozróżnienie łatwo przeoczyć, bo organizacja mintlify ma na GitHubie kilka repozytoriów na licencji MIT. Repozytorium mintlify/starter, czyli szkielet nowego projektu, ma około 1,9 tysiąca gwiazdek. Repozytorium mintlify/docs z treścią oficjalnej dokumentacji ma około 435 gwiazdek, a mintlify/components około 114. Wszystkie trzy są otwarte, żadne nie jest zarchiwizowane i żadne nie zawiera silnika. Otwarte są szablon i treść, zamknięty jest program, który je renderuje.

Sama Elastic License 2.0 jest licencją źródłowo dostępną, a nie otwartą w rozumieniu OSI, i jej najważniejsze ograniczenie brzmi bez owijania: nie wolno udostępniać oprogramowania osobom trzecim jako usługi hostowanej albo zarządzanej, która daje użytkownikom dostęp do istotnej części jego funkcji. Dla zespołu, który po prostu buduje własną dokumentację, ten zapis nie ma znaczenia praktycznego. Ma znaczenie dla każdego, kto chciałby na tym silniku postawić konkurencyjną usługę, oraz dla działu prawnego, który prowadzi listę licencji zależności i traktuje wszystko poza MIT, Apache i BSD jako pozycję do osobnego rozpatrzenia.

Do obrazu firmy dochodzi jeszcze jeden wątek. W marcu 2026 roku Mintlify przejęło Helicone, warstwę obserwowalności dla wywołań modeli językowych. Produkt trafił w tryb utrzymania, co opisujemy dokładniej w tekście o Helicone, a zespoły szukające dziś alternatywy trafiają zwykle na Langfuse. Dla oceny samego Mintlify to informacja o kierunku: firma kupuje kawałki układanki wokół pracy z modelami i konsoliduje je, a przejęte produkty nie zawsze dostają dalszy rozwój. Jeśli budujesz na czymś, co dostawca może przestawić w tryb utrzymania, warto mieć plan wyjścia. W przypadku dokumentacji plan wyjścia jest tani, bo treść to zwykłe pliki Markdown w Twoim repozytorium.

docs.json i struktura projektu

Cała konfiguracja siedzi w jednym pliku docs.json w katalogu głównym. Minimalna postać wymaga czterech pól, reszta jest opcjonalna.

{
  "$schema": "https://mintlify.com/docs.json",
  "theme": "mint",
  "name": "Acme Docs",
  "colors": {
    "primary": "#1a73e8"
  },
  "navigation": {
    "groups": [
      {
        "group": "Get started",
        "pages": ["index", "quickstart"]
      },
      {
        "group": "Guides",
        "pages": ["guides/first-steps", "guides/advanced"]
      }
    ]
  }
}

Odwołanie do $schema nie jest ozdobnikiem. Włącza podpowiadanie i sprawdzanie poprawności w edytorze, a przy pliku, który po pół roku ma kilkaset linii, to różnica między poprawką w edytorze a błędem wykrytym dopiero przy wdrożeniu.

Kiedy plik rośnie, można go rozbić polem $ref. Wstawiasz $ref ze ścieżką względną w dowolnym miejscu konfiguracji, a Mintlify podmienia obiekt na zawartość wskazanego pliku podczas budowania. Zasady są sztywne i dobrze, że są opisane: ścieżki muszą być względne i pozostawać wewnątrz katalogu projektu, więc ../../outside zostanie odrzucone, odwołania cykliczne kończą się błędem budowania, a klucze rodzeństwa w tym samym bloku nadpisują to, co przyszło z pliku wskazanego przez $ref.

Każda strona zaczyna się od bloku YAML. Pola są opcjonalne, ale kilka z nich decyduje o zachowaniu, które trudno potem odtworzyć z pamięci.

---
title: "Ustawianie limitów"
description: "Jak skonfigurować limity zapytań dla klucza API"
sidebarTitle: "Limity"
icon: "gauge"
tag: "beta"
noindex: false
searchable: true
---

Treść strony w MDX z komponentami platformy.

Pole hidden: true usuwa stronę z nawigacji i pociąga za sobą noindex: true. Dokumentacja ostrzega, że ustawienie hidden: false daje zachowanie niezdefiniowane, więc pole albo ma wartość true, albo znika z pliku. Pola noindex i searchable łatwo pomylić: pierwsze wypycha stronę z wyszukiwarki, mapy witryny i kontekstu asystenta, drugie wyłącza ją tylko z wyszukiwania na stronie i z kontekstu asystenta, zostawiając ją widoczną dla wyszukiwarek zewnętrznych.

Dokumentacja czytelna dla modeli

To jest realna przewaga tej platformy i warto rozłożyć ją na cztery osobne mechanizmy, bo bywają mylone.

Pierwszy to llms.txt, plik zgodny ze standardem opisanym na llmstxt.org, hostowany automatycznie w katalogu głównym strony i dodatkowo pod /.well-known/llms.txt. Zawiera spis wszystkich stron w formie linków Markdown ze streszczeniami, więc asystent najpierw czyta indeks, a dopiero potem pobiera to, czego potrzebuje. Własna wersja pliku jest możliwa, ale domyślna aktualizuje się sama.

Drugi to llms-full.txt, czyli cała treść dokumentacji sklejona w jeden plik. Skala robi tu różnicę i łatwo ją sprawdzić na dokumentacji samego Mintlify: llms.txt waży tam około 56 kilobajtów, a llms-full.txt około 1,5 megabajta. Pierwszy zmieści się w kontekście modelu bez zastanowienia, drugi wymaga dzielenia albo wyszukiwania i podawanie go asystentowi w całości zwykle nie ma sensu.

Trzeci mechanizm to wersja Markdown pojedynczej strony. Dopisujesz .md do adresu i zamiast HTML dostajesz źródło. Ten tekst powstał między innymi dzięki temu: adres dokumentacji z dopiskiem .md zwraca czysty Markdown, który da się przeczytać bez przedzierania się przez znaczniki układu, skrypty i style. Dla asystenta kodu to różnica między kilkoma tysiącami tokenów treści a kilkudziesięcioma tysiącami tokenów opakowania.

Czwarty to menu kontekstowe, sterowane polem contextual w docs.json. Opcje włącza się po identyfikatorach, a kolejność na liście wyznacza kolejność w menu.

{
  "contextual": {
    "options": [
      "copy",
      "view",
      "assistant",
      "chatgpt",
      "claude",
      "perplexity",
      "mcp",
      "cursor",
      "vscode",
      "download-spec"
    ],
    "display": "toc"
  }
}

Identyfikator copy kopiuje stronę jako Markdown, view otwiera ją jako Markdown, claude zakłada rozmowę w Claude z bieżącą stroną jako kontekstem, cursor instaluje Twój serwer MCP w Cursor, a download-spec pobiera specyfikację OpenAPI i pojawia się wyłącznie na stronach referencji API. Opcja download-pdf istnieje, ale jest oznaczona jako dostępna w planie Enterprise. Wartość display ustawiona na toc przenosi menu z nagłówka strony do bocznego spisu treści.

Wiersz poleceń: podgląd, walidacja i mint score

Narzędzie instaluje się globalnie albo uruchamia przez npx, a zestaw poleceń jest szerszy, niż sugeruje nazwa.

# instalacja i lokalny podgląd na porcie 3000
npm install -g mint
mint dev --port 4000 --no-open

# pominięcie przetwarzania OpenAPI, gdy specyfikacja jest duża
mint dev --disable-openapi

# budowanie w trybie ścisłym, kod wyjścia niezerowy przy ostrzeżeniach
mint validate

# osobne sprawdzenia treści
mint broken-links
mint a11y
mint format

# eksport strony do samodzielnego archiwum
mint export --output docs-offline.zip

# ocena gotowości strony dla agentów
mint score docs.example.com --format json

Polecenie mint validate zastępuje wycofany mint openapi-check i sprawdza także specyfikacje wskazane w docs.json, więc to ono powinno stać w potoku ciągłej integracji. Flaga --groups pozwala udawać przynależność do grup użytkowników, co jest jedynym sensownym sposobem obejrzenia treści za uwierzytelnianiem bez logowania się na prawdziwe konto.

Osobno stoi mint score, które odpytuje publiczny adres i wystawia ważoną ocenę gotowości dla agentów. Sprawdzenia mają czytelne nazwy i widać po nich, co dostawca uważa za istotne: llmsTxtExists, llmsTxtValid, llmsTxtSize, llmsTxtLinksResolve, llmsTxtFullExists, skillMd, contentNegotiationMarkdown, contentNegotiationPlaintext, mcpServerDiscoverable, mcpToolCount, openApiSpec, robotsTxtAllowsAI, sitemapExists, structuredData oraz responseLatency. Sprawdzenia zależne przepadają razem z tym, od którego zależą, więc brak llms.txt przewraca kilka pozycji naraz. Polecenie wymaga zalogowania przez mint login, ale przyjmuje dowolny adres, więc da się nim ocenić także cudzą dokumentację.

Jest jeszcze mint index, które instaluje hostowany serwer MCP indeksujący treści ze stron zbudowanych na Mintlify i podłącza go do klienta: --claude, --cursor, --vscode, --codex, --opencode, --windsurf albo --zed. To inny serwer niż ten opisujący Twoją własną dokumentację i mylenie ich prowadzi do zdziwienia, że agent nie widzi Twoich stron.

Cennik, plan darmowy i self-hosting

Strona cennika pokazuje trzy plany. Starter kosztuje zero dolarów miesięcznie i daje pięć miejsc edytorskich, pełną platformę, własną domenę, edytor w przeglądarce, uwierzytelnianie, serwer MCP i podgląd API. Jak na plan darmowy to sporo, bo elementy zwykle rezerwowane dla planów płatnych, czyli własna domena i serwer MCP, są tu od razu.

Pro pokazany jest jako 450 dolarów miesięcznie, przy czym nad ceną stoi przełącznik między rozliczeniem miesięcznym a rocznym i z surowej strony dało się odczytać tylko jedną liczbę. Traktuj ją jako wartość wyświetlaną domyślnie i sprawdź drugą u dostawcy przed podpisaniem czegokolwiek. Plan dorzuca nieograniczoną liczbę miejsc edytorskich, agenta, asystenta, automatyzacje, wdrożenia podglądowe i interfejsy administracyjne. To znaczy, że asystent odpowiadający czytelnikom na pytania w dokumentacji jest funkcją płatną, a nie elementem planu darmowego, i jeśli to on jest powodem wyboru Mintlify, plan Starter odpada od razu.

Enterprise ma cenę na zapytanie i obejmuje SSO, SCIM, kontrolę dostępu opartą na rolach, umowę o poziomie usług, rozszerzone statystyki oraz wsparcie przy migracji. Na tym poziomie pojawia się też uruchomienie u siebie. Dokumentacja jest tu uczciwa i pisze wprost, że nie jest to instalacja samoobsługowa, tylko zakres uzgadniany z zespołem dostawcy, liczony zwykle w tygodniach. Wdrożenie idzie przez aplikację AWS CDK albo przez wykres Helm na AKS, GKE, OKE, OpenShift lub dowolnym Kubernetesie. Ograniczenia są opisane równie jasno: funkcje związane z modelami są domyślnie wyłączone do czasu zgody działu bezpieczeństwa, integracje zależne od usług chmurowych Mintlify po prostu nie działają, aktualizacje przychodzą jako wydania wersjonowane, które sam wdrażasz, a monitoring podpinasz własny.

Strona cennika wspomina też o kredytach na pierwszy miesiąc, ale nie podaje ich liczby w treści strony, więc nie podajemy jej i my. Jeśli budujesz budżet, to jest pierwsze pytanie do działu sprzedaży.

Wdrożenie nie musi oznaczać osobnej domeny. Mintlify opisuje publikowanie dokumentacji pod podścieżką istniejącego serwisu, na przykład pod adresem kończącym się na /docs, przez reguły przepisywania po stronie serwera. Jeśli strona główna działa na Next.js, sprowadza się to do jednego wpisu w konfiguracji przepisań.

Mintlify a alternatywy

Wybór między platformą hostowaną a generatorem, który uruchamiasz sam, sprowadza się do pytania, czy chcesz płacić pieniędzmi, czy czasem zespołu. Poniżej dane sprawdzone w rejestrach pakietów i na stronach cenników dostawców.

Starlight jest motywem dla Astro, więc wchodzi razem z całym tym środowiskiem budowania. Docusaurus różni się od Mintlify przede wszystkim tym, że silnik jest otwarty i stoi na Twoim serwerze, a wersjonowanie i tłumaczenia dokumentacji ma w rdzeniu. Dwie wady trzeba jednak znać: wyszukiwarki w rdzeniu nie ma i standardowa droga prowadzi przez zewnętrzną usługę Algolii, darmową tylko dla publicznej dokumentacji technicznej po zaakceptowanym zgłoszeniu, a cała strona jest aplikacją Reacta, więc zespół bez Reacta odziedziczy ekosystem, którego nie chciał. Docusaurus i Starlight nie kosztują nic poza czasem: wyszukiwanie, wdrożenie, podgląd API i wyjścia dla modeli składasz sam z wtyczek i usług zewnętrznych. Przy dwuosobowym zespole to zwykle kilka dni pracy i stała drobna danina na utrzymanie. Przy dokumentacji, która jest częścią produktu i zmienia się codziennie, rachunek zaczyna wychodzić na korzyść platformy hostowanej.

Typowe błędy

Pierwszy błąd to uznanie Mintlify za projekt otwarty na podstawie repozytoriów widocznych na GitHubie. Otwarte na licencji MIT są szablon startowy, treść dokumentacji i biblioteka komponentów. Silnik jest zamknięty, wydawany na licencji Elastic 2.0, a repozytorium wskazane w manifeście pakietu nie odpowiada publicznie.

Drugi to planowanie wdrożenia na planie Starter i odkrycie w połowie drogi, że asystent, agent i automatyzacje zaczynają się dopiero w Pro. Listę funkcji planu przeczytaj przed migracją treści, nie po niej.

Trzeci to hidden: false w bloku YAML strony. Dokumentacja opisuje takie ustawienie jako zachowanie niezdefiniowane. Żeby pokazać stronę z powrotem, usuwa się całe pole.

Czwarty to mylenie noindex z searchable. Strona z searchable: false nadal trafia do mapy witryny i do wyszukiwarek zewnętrznych, więc nie jest to sposób na ukrycie czegokolwiek.

Piąty to brak mint validate w potoku ciągłej integracji. Bez tego zepsuta specyfikacja OpenAPI albo martwy odnośnik jedzie na produkcję, bo lokalny podgląd jest łaskawszy niż budowanie w trybie ścisłym.

Szósty to podawanie asystentowi pliku llms-full.txt w całości. Przy dokumentacji wielkości tej od Mintlify to półtora megabajta tekstu. Właściwą drogą jest indeks, potem pojedyncze strony z dopiskiem .md, ewentualnie serwer MCP.

Siódmy to rozbijanie docs.json przez $ref ze ścieżkami wychodzącymi poza katalog projektu. Wyjście w górę drzewa jest zablokowane, a odwołanie cykliczne kończy się błędem budowania.

FAQ

Czy Mintlify jest oprogramowaniem otwartym?

Nie. Pakiet mint w rejestrze npm ma licencję Elastic 2.0 i ten sam tekst licencji leży w opublikowanej paczce. Elastic License 2.0 jest licencją źródłowo dostępną, a nie otwartą, i zabrania udostępniania oprogramowania jako konkurencyjnej usługi hostowanej. Repozytoria mintlify/starter, mintlify/docs i mintlify/components są na licencji MIT, ale zawierają szablon, treść i komponenty, a nie silnik.

Co daje plan darmowy?

Plan Starter kosztuje zero dolarów, obejmuje pięć miejsc edytorskich, własną domenę, edytor w przeglądarce, uwierzytelnianie, hostowany serwer MCP i podgląd API. Poza nim zostają agent, asystent odpowiadający czytelnikom, automatyzacje, wdrożenia podglądowe i interfejsy administracyjne, które zaczynają się w planie Pro.

Czy muszę pisać w MDX?

Nie. Strony mogą być zwykłymi plikami .md i dokumentacja sama poleca taką drogę przy migracji z innej platformy, żeby najpierw przenieść treść. MDX jest potrzebny dopiero wtedy, gdy chcesz używać komponentów platformy, takich jak karty, akordeony czy pola opisujące odpowiedzi API.

Jak dokumentacja trafia do asystenta kodu?

Czterema drogami. Plik llms.txt w katalogu głównym daje indeks stron, llms-full.txt całą treść w jednym pliku, dopisek .md na końcu adresu zwraca źródło pojedynczej strony, a hostowany serwer MCP pozwala agentowi przeszukiwać treść narzędziem. Menu kontekstowe dokłada do tego przyciski otwierające bieżącą stronę w wybranym asystencie.

Czy da się uruchomić Mintlify na własnej infrastrukturze?

Tylko w planie Enterprise i tylko jako uzgodniony zakres wdrożenia, nie jako instalacja samoobsługowa. Dostępne drogi to aplikacja AWS CDK albo wykres Helm na AKS, GKE, OKE, OpenShift lub dowolnym Kubernetesie. Funkcje związane z modelami są wtedy domyślnie wyłączone, a integracje zależne od chmury dostawcy nie działają.

Co Mintlify zrobiło z Helicone?

Przejęło je w marcu 2026 roku i przestawiło w tryb utrzymania, czyli bez nowych funkcji. Wersja uruchamiana u siebie pozostaje na licencji Apache 2.0, a repozytorium Helicone/helicone nie jest zarchiwizowane. Szczegóły opisujemy osobno w tekście o Helicone.

Konfigurację i pełną listę pól znajdziesz w dokumentacji Mintlify, cennik na stronie planów, a szkielet nowego projektu w repozytorium startowym.