okineadev/vitepress-plugin-llms

무엇인가요

vitepress‑plugin‑llms 는 빌드 시 문서의 LLM 친화적 버전을 자동으로 생성하는 VitePress 플러그인입니다. 일반 텍스트 Markdown 파일(llms.txt에는 섹션 링크 포함, llms‑full.txt에는 전체 사이트 포함)과 방문자가 페이지를 복사하거나 Markdown으로 다운로드할 수 있도록 도와주는 선택적 UI 도구를 생성합니다.

왜 사용하고 싶을까

대규모 언어 모델(LLM)은 깨끗하고 가벼운 텍스트에서 가장 잘 작동합니다. 기존의 VitePress 출력에는 HTML, 네비게이션, UI 전용 마크업이 포함되어 LLM을 혼란스럽게 만들 수 있습니다. 이 플러그인은 원본 Markdown을 추출하고, 세밀한 제어를 위한 선택적 태그(<llm‑only> / <llm‑exclude>)를 추가하며, llmstxt.org v2 표준을 따르므로, 후속 AI 도구(예: 검색 기반 생성, 인덱싱, 파인튜닝)에 바로 사용할 수 있는 문서를 제공합니다.

시작하기

npm install vitepress-plugin-llms --save-dev

.vitepress/config.ts 에 플러그인을 추가합니다:

import { defineConfig } from 'vitepress'
import llmstxt from 'vitepress-plugin-llms'

export default defineConfig({
  vite: { plugins: [llmstxt()] },
})

선택적으로 사용자에게 "Markdown으로 복사" / "Markdown으로 다운로드" 버튼을 제공하기 위해 번들된 Vue 컴포넌트를 등록합니다:

import DefaultTheme from 'vitepress/theme'
import CopyOrDownloadAsMarkdownButtons from 'vitepress-plugin-llms/vitepress-components/CopyOrDownloadAsMarkdownButtons.vue'

export default {
  extends: DefaultTheme,
  enhanceApp({ app }) { app.component('CopyOrDownloadAsMarkdownButtons', CopyOrDownloadAsMarkdownButtons) },
}

그런 다음 Markdown 변환기를 활성화합니다:

import { copyOrDownloadAsMarkdownButtons } from 'vitepress-plugin-llms'

export default defineConfig({
  markdown: { config(md) { md.use(copyOrDownloadAsMarkdownButtons) } },
})

커스텀 UI를 원한다면 useCopyOrDownloadAsMarkdownButtons composable도 사용할 수 있습니다.

UI 텍스트 커스터마이징

라벨은 themeConfig.llms (또는 locales.<locale>.themeConfig.llms 에서 로케일별로)에서 읽어옵니다. 모든 키는 선택 사항입니다:

키	기본값
copyText	Copy page
copiedText	Copied
viewMarkdownText	View as Markdown
openInAIText	Open in {provider}

LLM 전용 또는 LLM 제외 콘텐츠를 위한 특수 마크업

• <llm-only> – 이 태그 내의 콘텐츠는 생성된 llms.txt 파일에 포함되지만, 인간 독자에게는 숨겨집니다.
• <llm-exclude> – 이 태그 내의 콘텐츠는 인간 독자에게는 표시되지만, LLM 파일에서는 제외됩니다.

검증

배포 후 생성된 llms.txt URL이 여전히 유효한지 확인하기 위해 도우미 도구 llms‑txt‑check 를 사용할 수 있습니다:

npx llms-txt-check https://your-docs-site.com

목록된 URL 중 하나라도 손상된 경우 비제로 코드로 종료됩니다.

주요 기능 (요약)

• ✅ VitePress에 대한 제로 설정 통합
• ⚙️ VitePress 테마 설정을 통해 완전히 사용자 정의 가능
• 🤖 페이지별 LLM 친화적 Markdown과 두 개의 인덱스 파일(llms.txt, llms‑full.txt) 생성
• 📋 선택적 "Markdown으로 복사/다운로드" UI 컴포넌트
• 🏷️ 세밀한 콘텐츠 제어를 위한 <llm-only> / <llm-exclude> 태그
• 📦 Bun으로 구축, oxc로 포맷팅, 자동 CI 테스트 완료

누가 사용하고 있나요

README에는 Vite, Vue.js, Vitest, Rolldown 등의 유명 프로젝트와 이미 사이트에서 llms.txt 및 llms‑full.txt 를 공개하고 있는 몇몇 초기 사용자들이 나와 있습니다.

라이선스 및 기여

MIT 라이선스. 기여는 링크된 CONTRIBUTING.md 를 통해 환영하며, 프로젝트는 GitHub를 통해 스폰서십을 수락합니다.