LangChain 문서 기여하기

LangChain 문서 기여하기 (Contributing to documentation)

LangChain 문서는 새 기능, 통합(integration), 기존 문서 개선을 포함해서 기여를 환영해요. 이 페이지는 로컬에서 문서 미리보기를 띄우고, 품질 검사를 통과해 풀 리퀘스트를 올리기까지의 흐름을 한 번에 안내드릴게요. 처음 기여하시는 분도 그대로 따라 하시면 돼요.

출처: 공식문서

빠른 시작 - 로컬 개발

문서의 로컬 미리보기를 띄우려면 이렇게 하시면 돼요.

git clone https://github.com/langchain-ai/docs.git
cd docs

그다음 고정된 툴체인을 mise로 설치해요. mise가 .mise.toml에서 Python, Node.js, uv, Vale, Mintlify CLI 버전을 읽어서 설치하고, 저장소의 git 훅까지 붙여 줘요.

mise trust && mise install
make install
make dev

이렇게 하면 http://localhost:3000에서 핫 리로드가 되는 개발 서버가 떠요. src/의 파일을 수정하면 변경이 즉시 반영돼요.

AI 코딩 에이전트를 쓰시나요? LangChain Docs MCP 서버를 설치하면 에이전트가 최신 LangChain 문서와 예제를 참고할 수 있어요. LangChain Skills를 설치하면 LangChain 생태계 작업에서 에이전트 성능이 좋아지고, 페이지 오른쪽 위의 Copy page 버튼으로 원문을 복사해 에이전트에 붙여 넣으면 환경을 자동으로 세팅해 줘요. 이 저장소는 .agents/skills/에 자체 authoring 스킬을 싣고 있는데, 페이지 생성·내비게이션 배치·리다이렉트를 다루죠. 대부분의 에이전트는 그 경로를 직접 읽고요, Claude Code에서는 make skills를 실행해 링크할 수 있어요. 로컬 미리보기에 문제가 생기면 mint update를 실행해 Mintlify 버전을 최신으로 맞춰 보세요.

전제 조건

문서를 수정하기 전에 알아두면 좋은 규칙이에요.

  • src/의 파일만 수정해요. build/ 디렉터리는 자동으로 생성되니 건드리지 마세요.
  • 작성 기준(writing standards)에 맞춰 src/의 파일을 편집해요.
  • 제출 전에 품질 검사를 돌려요.
  • 검토를 받으러 풀 리퀘스트를 올려요.
  • 모든 풀 리퀘스트는 메인테이너가 승인한 이슈나 토론을 반드시 연결해야 해요. (풀 리퀘스트 요구사항 참고)

품질 검사 실행

제출 전에 포맷·린트 검사가 통과하는지 확인해 주세요.

# 끊어진 링크 확인
make broken-links

# 코드 자동 포맷
make format

# 린트 문제 확인
make lint

# 마크다운 문제 수정
make lint_md_fix

# 기존 기능을 깨뜨리지 않는지 테스트
make test

더 자세한 내용은 README의 사용 가능한 명령어 섹션을 참고하세요.

문서 유형

모든 문서는 네 가지 범주 중 하나에 속해요.

  • How-to 가이드 — 무엇을 해내고 싶은지 아는 사용자를 위한 작업 지향 지침
  • 개념 가이드 — 더 깊은 이해와 통찰을 주는 설명
  • 레퍼런스 — API와 구현 세부사항의 기술적 설명
  • 튜토리얼 — 실습 활동을 통해 이해를 쌓는 수업

가능하면 모든 문서는 Python과 JavaScript/TypeScript 내용을 모두 가져야 해요. 자세한 건 "Python·JavaScript/TypeScript 콘텐츠 함께 배치" 섹션을 보세요.

How-to 가이드

How-to 가이드는 무엇을 해내고 싶은지 아는 사용자를 위한 작업 지향 지침이에요. LangChain과 LangGraph 탭에서 예시를 볼 수 있어요.

개념 가이드

개념 가이드는 핵심 개념을 추상적으로 다루며 깊은 이해를 제공해요.

레퍼런스

레퍼런스 문서는 정확히 어떤 기능이 존재하고 어떻게 쓰는지 설명하는 상세한 저수준 정보를 담아요.

  • Python 레퍼런스, JavaScript/TypeScript 레퍼런스가 있어요.
  • 좋은 레퍼런스는 다음을 충족해야 해요.
    • 무엇이 존재하는지 기술 (모든 파라미터, 옵션, 반환값)
    • 쉽게 찾을 수 있게 포괄적이고 구조화
    • 기술 세부사항의 권위 있는 출처 역할

튜토리얼

튜토리얼은 스스로를 이어가며 특정 실습 활동을 안내하는, 보다 긴 단계별 가이드예요. 보통 Learn 탭에서 찾아볼 수 있죠. 외부 기여자의 새 튜토리얼은 긴급한 필요가 없다면 일반적으로 병합하지 않아요. 문서에서 빠진 주제나 부족한 부분이 있다고 생각되면 새 이슈를 열어 주세요.

작성 기준 (Writing standards)

reference.langchain.com의 페이지에 대한 기준은 이 저장소가 아니라 해당 사이트의 빌드 파이프라인에 있어요. 생성된 API 레퍼런스 콘텐츠에 대한 질문이나 수정은 레퍼런스 문서 이슈 템플릿을 사용해 주세요.

Mintlify 컴포넌트

가독성을 높이기 위해 Mintlify 컴포넌트를 사용할 수 있어요. 구조(Structure)·코드(Code) 컴포넌트와 함께 콜아웃(Callout)을 쓰면 되는데, 용도가 정해져 있어요.

  • <Note> — 도움이 되는 부가 정보
  • <Warning> — 중요한 주의사항과 브레이킹 체인지
  • <Tip> — 모범 사례와 조언
  • <Info> — 중립적인 맥락 정보
  • <Check> — 성공 확인

Mermaid 다이어그램

Mermaid 다이어그램을 추가할 때는 노드 스타일링에 LangChain 브랜드 색상 팔레트를 사용해야 해요. 기존 다이어그램에서 classDef 줄을 복사하거나, CLAUDE.md의 레퍼런스 표를 사용해 주세요.

역할(Role) Fill Stroke Text
process #E5F4FF #006DDD #030710
trigger #F6FFDB #6E8900 #2E3900
decision #FDF3FF #7E65AE #504B5F
output #EBD0F0 #885270 #441E33
alert #F8E8E6 #B27D75 #634643
neutral #F2FAFF #40668D #2F4B68

Tailwind 기본값이나 Material Design 색상 같은 브랜드 외 팔레트는 사용하지 마세요.

페이지 구조

모든 문서 페이지는 YAML frontmatter로 시작해야 해요.

---
title: "Clear, specific title"
sidebarTitle: "Short title for the sidebar (optional)"
---

Python·JavaScript/TypeScript 콘텐츠 함께 배치

가능한 모든 문서는 Python과 JavaScript/TypeScript 양쪽으로 작성해야 해요. 이때 커스텀 인라인 문법으로 언어별 섹션을 구분해요.

:::python
Python-specific content.
:::

:::js
JavaScript/TypeScript-specific content.
:::

Content for both languages (not wrapped)

이렇게 하면 /oss/python/concepts/foo.mdx와 /oss/javascript/concepts/foo.mdx 두 출력물이 생겨요. 각 출력 페이지는 내비게이션에 포함되도록 /src/docs.json 파일에 추가해야 해요.

패리티(parity)가 없다고 기여를 막지는 않아요. 기능이 한 언어에만 있다면 상대 언어가 따라잡을 때까지 그 언어로만 문서화해도 괜찮아요. 그럴 땐 다른 언어에는 아직 기능이 없다는 메모를 남겨 주세요. Python과 JavaScript/TypeScript 간 번역이 필요하면 커뮤니티 슬랙에 물어보거나 PR에서 메인테이너를 태그해 주세요.

품질 기준

일반 지침

  • 중복 피하기
  • 링크 자주 걸기
  • 간결하게 쓰기

접근성 요구사항

모든 사용자가 문서에 접근할 수 있게 해주세요.

  • 헤더와 목록으로 쉽게 훑을 수 있게 구조화
  • "click here" 대신 구체적이고 행동 가능한 링크 텍스트 사용
  • 모든 이미지와 다이어그램에 설명 alt 텍스트 포함

상호 참조 (Cross-referencing)

문서와 API 레퍼런스 문서를 연결할 때는 일관된 교차 참조를 사용해요.

문서 → API 레퍼런스로는 @[] 문법을 써서 API 레퍼런스 페이지를 연결해요.

See @[`ChatAnthropic`] for all configuration options.
The @[`bind_tools`][ChatAnthropic.bind_tools] method accepts...

빌드 파이프라인이 이 문법을 현재 언어 스코프(Python 또는 JavaScript)에 맞는 마크다운 링크로 변환해요. 예를 들어 @[ChatAnthropic]는 빌드되는 문서 버전에 따라 Python 또는 JS API 레퍼런스 페이지로 연결돼요. 단, link_map.py 파일에 항목이 있을 때만 가능해요. (autolinks 동작 방식 참고)

API 레퍼런스 스텁 → OSS 문서로는, 게시된 Python API 레퍼런스의 교차 링크와 딥 앵커는 이 저장소 밖에서 생성돼요. reference.langchain.com에서 docs.langchain.com으로 가는 링크가 틀렸거나 낡았다면 출발·도착 URL과 함께 이슈를 열어 주세요.

지역화 (Localization)

두 SDK 모두에 존재하는 기능이면 Python과 JavaScript/TypeScript를 함께 문서화해요. 한 언어만 지원된다면 해당 기능과 그에 대한 참조가 그 언어에서만 보이게 해야 해요.

코드 내 문서화

예제는 정확해야 하고, 가능하면 복사해서 붙여 넣어 바로 쓸 수 있어야 하며, 풀 리퀘스트를 열기 전에 테스트해야 해요. 실행 불가능한 스니펫(의사코드·예시 조각 등)은 명확히 표시해 주세요.

도움 받기

목표는 가능한 한 가장 단순한 개발자 세팅을 제공하는 거예요. 세팅에 어려움이 있으면 커뮤니티 슬랙에 물어보거나 포럼에 글을 올려 주세요. 내부 팀원은 #documentation 슬랙 채널에서 소통할 수 있어요.

더 알아보기 (Learn more)