docs: add usage on documentation

README-ko_kr.md

@@ -0,0 +1,38 @@
+# es-git · [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/toss/es-git/blob/main/LICENSE) [![NPM badge](https://img.shields.io/npm/v/es-git?logo=npm)](https://www.npmjs.com/package/es-git)
+
+[English](https://github.com/toss/es-git/blob/main/README.md) | 한국어
+
+es-git은 Node.js를 위한 현대적인 git 라이브러리예요. 간편하고 직관적인 인터페이스 덕분에 복잡한 git 작업도 쉽게 통합할 수 있으며, TypeScript 타입을 내장해 빠르고 안정적인 개발을
+지원해요.
+
+es-git은 libgit2를 바인딩한 [git2-rs](https://github.com/rust-lang/git2-rs)를 [napi-rs](https://napi.rs/)를 사용해 네이티브 모듈로 빌드하여,
+운영체제와 상관없이 고성능 git 기능을 제공해요.
+
+또한, node-gyp를 사용하지 않고 운영체제 및 cpu 아키텍처에 맞는 사전 빌드된 네이티브 모듈을 제공하기 때문에 사용자 환경에서 빌드하지 않고 간편하게
+모듈을 설치할 수 있어요.
+
+## 예제
+
+```ts
+import { cloneRepository } from 'es-git';
+
+const repo = await cloneRepository('https://github.com/toss/es-git', '/path/to/clone');
+const head = repo.head().name();
+console.log(head); // "refs/heads/main"
+```
+
+## 문서
+
+- [사용법](https://es-git.slash.page/ko/usage/open)
+- [API](https://es-git.slash.page/ko/api/globals)
+
+## 라이센스
+
+MIT © Viva Republica, Inc. 자세한 내용은 [LICENSE](./LICENSE)를 참고하세요.
+
+<a title="Toss" href="https://toss.im">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://static.toss.im/logos/png/4x/logo-toss-reverse.png">
+    <img alt="Toss" src="https://static.toss.im/logos/png/4x/logo-toss.png" width="100">
+  </picture>
+</a>

README.md

@@ -1,4 +1,30 @@
-# es-git
+# es-git · [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/toss/es-git/blob/main/LICENSE) [![NPM badge](https://img.shields.io/npm/v/es-git?logo=npm)](https://www.npmjs.com/package/es-git) 
+
+English | [한국어](https://github.com/toss/es-git/blob/main/README-ko_kr.md)
+
+es-git is a modern git library built for Node.js. With its simple and intuitive interface, even complex git operations
+can be easily integrated, and the built-in TypeScript types ensure fast and reliable development.
+
+es-git builds high-performance git functionality across different operating systems by using [napi-rs](https://napi.rs/)
+to compile a native module from [git2-rs](https://github.com/rust-lang/git2-rs), which binds to libgit2.
+
+Furthermore, by offering pre-built native modules tailored to your OS and CPU architecture without relying
+on node-gyp, the module can be installed effortlessly without the need to build it locally.
+
+## Examples
+
+```ts
+import { cloneRepository } from 'es-git';
+
+const repo = await cloneRepository('https://github.com/toss/es-git', '/path/to/clone');
+const head = repo.head().name();
+console.log(head); // "refs/heads/main"
+```
+
+## Documentation
+
+- [사용법](https://es-git.slash.page/usage/open)
+- [API](https://es-git.slash.page/api/globals)
 
 ## License
 

docs/.vitepress/config.ts

@@ -9,5 +9,5 @@ export default defineConfig({
     root: { label: 'English', ...en },
     ko: { label: '한국어', ...ko },
   },
-  ignoreDeadLinks: ['./index', './classes/index'],
+  ignoreDeadLinks: [/\/index/],
 });

docs/.vitepress/en.ts

@@ -6,7 +6,7 @@ const docsRoot = path.resolve(import.meta.dirname, '..');
 
 export const en = defineConfig({
   lang: 'en',
-  description: 'TODO',
+  description: 'Modern git library built for Node.js',
   themeConfig: {
     nav: nav(),
     sidebar: sidebar(),
@@ -24,7 +24,8 @@ export const en = defineConfig({
 function nav(): DefaultTheme.NavItem[] {
   return [
     { text: 'Home', link: '/' },
-    { text: 'Introduction', link: '/intro' },
+    { text: 'About', link: '/about' },
+    { text: 'Usage', link: '/usage/open' },
   ];
 }
 
@@ -33,13 +34,25 @@ function sidebar(): DefaultTheme.Sidebar {
     {
       text: 'Guide',
       items: [
-        { text: 'Introduction', link: '/intro' },
-        { text: 'Installation & Usage', link: '/usage' },
+        { text: 'About', link: '/about' },
+        { text: 'Installation', link: '/install' },
+      ],
+    },
+    {
+      text: 'Usage',
+      items: [
+        { text: 'Opening a Repository', link: '/usage/open' },
+        { text: 'Cloning a Repository', link: '/usage/clone' },
+        { text: 'Remotes', link: '/usage/remote' },
+        { text: 'Commit History', link: '/usage/history' },
+        { text: 'Commit Changes', link: '/usage/commit' },
+        { text: 'Tags', link: '/usage/tag' },
       ],
     },
     {
       text: 'API',
       collapsed: true,
+      link: '/api/globals',
       items: getAPISidebarItems(docsRoot),
     },
   ];

docs/.vitepress/ko.ts

@@ -6,7 +6,7 @@ const docsRoot = path.resolve(import.meta.dirname, '..');
 
 export const ko = defineConfig({
   lang: 'ko',
-  description: 'TODO',
+  description: 'Node.js를 위한 현대적인 git 라이브러리',
   themeConfig: {
     nav: nav(),
     sidebar: sidebar(),
@@ -24,7 +24,8 @@ export const ko = defineConfig({
 function nav(): DefaultTheme.NavItem[] {
   return [
     { text: '홈', link: '/ko' },
-    { text: '소개', link: '/ko/intro' },
+    { text: '소개', link: '/ko/about' },
+    { text: '사용법', link: '/ko/usage/open' },
   ];
 }
 
@@ -33,13 +34,25 @@ function sidebar(): DefaultTheme.Sidebar {
     {
       text: '가이드',
       items: [
-        { text: '소개', link: '/ko/intro' },
-        { text: '설치 및 사용 방법', link: '/ko/usage' },
+        { text: '소개', link: '/ko/about' },
+        { text: '설치하기', link: '/ko/install' },
+      ],
+    },
+    {
+      text: '사용법',
+      items: [
+        { text: '리포지토리 열기', link: '/ko/usage/open' },
+        { text: '리포지토리 복제하기', link: '/ko/usage/clone' },
+        { text: '리모트', link: '/ko/usage/remote' },
+        { text: '커밋 히스토리', link: '/ko/usage/history' },
+        { text: '커밋하기', link: '/ko/usage/commit' },
+        { text: '태그', link: '/ko/usage/tag' },
       ],
     },
     {
       text: 'API',
       collapsed: true,
+      link: '/ko/api/globals',
       items: getAPISidebarItems(docsRoot, 'ko'),
     },
   ];

docs/.vitepress/lib/sidebar.ts

@@ -1,22 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import glob from 'fast-glob';
 import type { DefaultTheme } from 'vitepress';
 
-export function getSidebarItems(docsRoot: string, ...parts: string[]): DefaultTheme.SidebarItem[] {
-  const files = glob.sync(path.join(docsRoot, ...parts, '*'));
-  const paths = files.map(x => `/${path.relative(docsRoot, x)}`);
-
-  return paths.map(p => {
-    const filename = path.basename(p).replace(/\.md$/g, '');
-
-    return {
-      text: filename,
-      link: p.replace(/\.md$/g, ''),
-    };
-  });
-}
-
 export function getAPISidebarItems(docsRoot: string, lang?: string) {
   const jsonFilepath =
     lang != null

docs/about.md

@@ -0,0 +1,16 @@
+# About es-git
+
+es-git is a modern git library built for Node.js. With its simple and intuitive interface, even complex git operations
+can be easily integrated, and the built-in TypeScript types ensure fast and reliable development.
+
+es-git builds high-performance git functionality across different operating systems by using [napi-rs](https://napi.rs/)
+to compile a native module from [git2-rs](https://github.com/rust-lang/git2-rs), which binds to libgit2.
+
+Furthermore, by offering pre-built native modules tailored to your OS and CPU architecture without relying
+on node-gyp, the module can be installed effortlessly without the need to build it locally.
+
+## Links
+
+Please refer to the following links for more information about this project.
+
+- [GitHub](https://github.com/toss/es-git)

docs/index.md

@@ -4,13 +4,13 @@ layout: home
 
 hero:
   name: 'es-git'
-  text: 'TODO'
+  text: 'Modern git library built for Node.js'
   # tagline:
   actions:
     - theme: brand
       text: About es-git
-      link: /intro
+      link: /about
     - theme: alt
       text: Usage
-      link: /usage
+      link: /usage/open
 ---

docs/usage.md → docs/install.md

@@ -1,11 +1,11 @@
 ---
-description: How to use es-git
+description: Install es-git
 prev:
-  text: Introduction to es-git
-  link: ./intro.md
+  text: About es-git
+  link: ./about.md
 ---
 
-# Installation & Usage
+# Installation
 
 es-git is available via [npm](https://npmjs.com/package/es-git).
 

docs/ko/about.md

@@ -0,0 +1,16 @@
+# es-git 소개
+
+es-git은 Node.js를 위한 현대적인 git 라이브러리예요. 간편하고 직관적인 인터페이스 덕분에 복잡한 git 작업도 쉽게 통합할 수 있으며, TypeScript 타입을 내장해 빠르고 안정적인 개발을
+지원해요.
+
+es-git은 libgit2를 바인딩한 [git2-rs](https://github.com/rust-lang/git2-rs)를 [napi-rs](https://napi.rs/)를 사용해 네이티브 모듈로 빌드하여,
+운영체제와 상관없이 고성능 git 기능을 제공해요.
+
+또한, node-gyp를 사용하지 않고 운영체제 및 cpu 아키텍처에 맞는 사전 빌드된 네이티브 모듈을 제공하기 때문에 사용자 환경에서 빌드하지 않고 간편하게
+모듈을 설치할 수 있어요.
+
+## 링크
+
+이 프로젝트에 대해서 더 많은 정보를 얻기 위해서는 아래 링크를 참고하세요.
+
+- [GitHub](https://github.com/toss/es-git)

docs/ko/index.md

@@ -4,13 +4,13 @@ layout: home
 
 hero:
   name: 'es-git'
-  text: 'TODO'
+  text: 'Node.js를 위한 현대적인 git 라이브러리'
   # tagline:
   actions:
     - theme: brand
       text: es-git 알아보기
-      link: /ko/intro
+      link: /ko/about
     - theme: alt
-      text: 설치 및 사용
-      link: /ko/usage
+      text: 사용법
+      link: /ko/usage/open
 ---

docs/ko/usage.md → docs/ko/install.md

@@ -1,11 +1,11 @@
 ---
-description: es-git을 사용하는 방법
+description: es-git 설치하기
 prev:
   text: es-git 소개
-  link: ./intro.md
+  link: ./about.md
 ---
 
-# 설치 및 사용하기
+# 설치하기
 
 es-git은 [npm](https://npmjs.com/package/es-git)에서 설치할 수 있어요.
 

docs/ko/usage/clone.md

@@ -0,0 +1,73 @@
+# 리포지토리 복제 하기
+
+기존 리포지토리를 복사하기 위해 [`cloneRepository()`](../api/functions/cloneRepository.md)를 사용할 수 있어요. 리모트에서 복사하기 위해 `https://`, `git://` 혹은 `user@server:path/to/repo.git` 처럼
+SSH 프로토콜을 사용할 수 있어요.
+
+```ts
+import { cloneRepository } from 'es-git';
+
+const repo = await cloneRepository('https://github.com/toss/es-git', '/path/to/clone');
+```
+
+## 인증
+
+리포지토리를 클론할 때 `credential` 옵션을 설정해 인증이 가능해요.
+
+```ts
+import { cloneRepository } from 'es-git';
+
+// ssh-agent를 통해 인증
+const cloneWithSshAgent = await cloneRepository('git@github.com:toss/es-git', '.', {
+  fetch: {
+    credential: {
+      type: 'SSHKeyFromAgent',
+    },
+  },
+});
+
+// 로컬에 저장된 ssh키 파일을 통해 인증
+const cloneWithSshKeyFromPath = await cloneRepository('git@github.com:toss/es-git', '.', {
+  fetch: {
+    credential: {
+      type: 'SSHKeyFromPath',
+      privateKeyPath: '/path/to/ssh/private/key',
+    },
+  },
+});
+
+// ssh키를 입력해 인증
+const cloneWithSshKey = await cloneRepository('git@github.com:toss/es-git', '.', {
+  fetch: {
+    credential: {
+      type: 'SSHKey',
+      privateKey: 'MY_PRIVATE_SSH_KEY',
+    },
+  },
+});
+
+// plain 비밀번호를 통해 인증
+const cloneWithPlain = await cloneRepository('https://github.com/toss/es-git', '.', {
+  fetch: {
+    credential: {
+      type: 'Plain',
+      password: 'MY_PASSWORD',
+    },
+  },
+});
+```
+
+GitHub [개인용 액세스 토큰](https://docs.github.com/ko/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
+을 사용중이라면, "Plain" 유형의 `credential` 옵션을 지정해 비공개 리포지토리를 클론받을 수 있어요.
+
+```ts
+import { cloneRepository } from 'es-git';
+
+const repo = await cloneRepository('https://github.com/<owner>/<repo>', '.', {
+  fetch: {
+    credential: {
+      type: 'Plain',
+      password: '<personal access token>',
+    },
+  },
+});
+```