docs: add documentation page

.github/workflows/documents.yml

@@ -0,0 +1,69 @@
+name: documents
+
+on:
+  # run every time a push occurs in the docs folder
+  push:
+    branches: [master]
+    paths:
+      - docs/**
+      - .github/workflows/documents.yml
+      - package.json
+      - package-lock.json
+  # trigger deployment manually
+  workflow_dispatch:
+
+jobs:
+  build-documentation-pages:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # fetch all commits to get last updated time or other git log info
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      # cache node_modules
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        id: npm-cache
+        with:
+          path: |
+            **/node_modules
+          key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-npm-
+
+      # copy changelog.md file
+      - name: Copy CHANGELOG.md file
+        run: |
+          cp CHANGELOG.md ./docs/en/changelog.md
+          cp CHANGELOG.md ./docs/ko/changelog.md
+
+      # install dependencies if the cache did not hit
+      - name: Install dependencies
+        if: steps.npm-cache.outputs.cache-hit != 'true'
+        run: npm install
+
+      # run build script
+      - name: Build VitePress site
+        run: npm run docs:build
+
+      # please check out the docs of the workflow for more details
+      # @see https://github.com/crazy-max/ghaction-github-pages
+      - name: Deploy to GitHub Pages
+        uses: crazy-max/ghaction-github-pages@v4
+        with:
+          # deploy to gh-pages branch
+          target_branch: gh-pages
+          # deploy the default output dir of VitePress
+          build_dir: docs-dist
+          jekyll: false
+          fqdn: 'vitepress-i18n.cdget.com'
+        env:
+          # @see https://docs.github.com/en/actions/reference/authentication-in-a-workflow#about-the-github_token-secret
+          GITHUB_TOKEN: ${{ secrets.ACCESS_TOKEN }}

.gitignore

@@ -58,3 +58,10 @@ $RECYCLE.BIN/
 
 # Project files
 dist/
+docs-dist/
+
+# VitePress files
+docs/.vitepress/.temp
+docs/.vitepress/.temp/*
+docs/.vitepress/cache
+docs/.vitepress/cache/*

.npmignore

@@ -10,6 +10,8 @@ Thumbs.db
 # Project files
 lib/
 test/
+docs/
+docs-dist/
 CHANGELOG.md
 CODE_OF_CONDUCT.md
 

.prettierignore

@@ -1,6 +1,8 @@
-dist/
+dist
+docs-dist/
 .idea/
 .vscode/
+docs/.vitepress/cache
 node_modules/
 
 package-lock.json

README.md

@@ -8,34 +8,13 @@
 - ⚡️ Lightweight bundle file size, zero dependencies
 - ⚡️ [TypeScript](https://www.typescriptlang.org) support
 
-## Installation
+> [!NOTE]
+>
+> Currently, the plugin is experimental and production-ready, but many features may be missing. The documentation page is still a work in progress. If you run into behavioral issues, please create a new issue!
 
-First, you may need to pre-configure **[VitePress](https://vitepress.dev)** before using this module.
+## [Documentation (Getting Started & All option lists)](https://vitepress-i18n.cdget.com/guide/getting-started)
 
-We recommend using **Node.js 18.x** or higher. The **VitePress i18n** is written in `ESM`.
-
-You will need to install the module using [NPM](https://www.npmjs.com/package/vitepress-i18n) or any other Node module package manager. The package should be installed in `devDependencies` as it is only used in the developer environment. Use the command below:
-
-```shell
-# via npm
-$ npm i -D vitepress-i18n
-
-# via yarn
-$ yarn add -D vitepress-i18n
-
-# via pnpm
-$ pnpm i -D vitepress-i18n
-```
-
-## How to use
-
-VitePress i18n comes with a function to translate the general layout text (`generateI18nLocale`) and a function to translate the search interface (`generateI18nSearch`).
-
-Each function must be called from a specific location in VitePress's configuration file. VitePress's configuration file is typically located at `.vitepress/config.ts`.
-
-In VitePress' i18n, you can customize the locale key. For example, if you specify `kor` as the locale key for Korean translation, you can use a URL like `/kor/docs/abc`. This plugin requires you to properly configure `defineLocales` in the parameter so that it can tell it to translate a specific locale key into the language you specify.
-
-For example, to translate what is specified as the `kor` key into Korean, add the following to the values in the `defineLocales` array: `{ label: 'kor', translateLocale: 'ko' }`
+Installing and using the package and defining all the utility methods can be found on the documentation page below: https://vitepress-i18n.cdget.com/guide/getting-started
 
 The currently supported translation languages and `translateLocale` matching values are as follows:
 
@@ -55,19 +34,26 @@ The currently supported translation languages and `translateLocale` matching val
 - `*` Vietnamese (Tiếng Việt): `vi`
 - `*` Italian (Italiano): `it`
 
-If a `rootLocale` value is specified, set the language key to `root` if the label language and the `rootLocale` value are the same. In the remaining areas, it does not need to be specified as `root`.
-
-It will then use the same parameters that VitePress already uses. Note, however, that you must declare custom values for each of the keys you specify in `defineLocales`.
+## Example
 
-## Methods: `generateI18nLocale`
+### Basic configurations
 
-Call this function with the `locales` option in VitePress's root config:
+```javascript
+export default defineConfig({
+  ...generateI18n({
+    defineLocales: [
+      { label: 'en', translateLocale: 'en' },
+      { label: 'ko', translateLocale: 'ko' }
+    ]
+  })
+});
+```
 
-### Example
+### With custom label
 
 ```javascript
 export default defineConfig({
-  locales: generateI18nLocale({
+  ...generateI18n({
     defineLocales: [
       { label: 'en', translateLocale: 'en' },
       { label: 'ko', translateLocale: 'ko' }
@@ -95,6 +81,8 @@ export default defineConfig({
 {
   defineLocales: DefineLocales[];
   rootLocale?: string;
+  searchProvider?: 'local' | 'algolia';
+  searchOptions?: { [key: string]: any };
   disableAutoSetLangValue?: boolean;
   debugPrint?: boolean;
   editLinkPattern?: string;
@@ -109,35 +97,6 @@ export default defineConfig({
 }
 ```
 
-## Methods: `generateI18nSearch`
-
-Call this function on the `search` option of VitePress's `themeConfig`:
-
-### Example
-
-```javascript
-export default defineConfig({
-  themeConfig: {
-    search: generateI18nSearch({
-      defineLocales: [{ label: 'ko', translateLocale: 'ko' }],
-      rootLocale: 'en',
-      provider: 'local'
-    })
-  }
-});
-```
-
-### Parameters
-
-```text
-{
-  defineLocales: DefineLocales[];
-  rootLocale?: string;
-  provider: 'local' | 'algolia';
-  options?: LocalSearchOptions;
-}
-```
-
 ## Contribute
 
 You can report issues on [GitHub Issue Tracker](https://github.com/jooy2/vitepress-i18n/issues).

docs/.vitepress/config.ts

@@ -0,0 +1,71 @@
+import { generateSidebar, VitePressSidebarOptions } from 'vitepress-sidebar';
+import { repository, homepage } from '../../package.json';
+import { defineConfig, UserConfig } from 'vitepress';
+import { generateI18n } from '../../dist';
+
+const defaultLocale: string = 'en';
+const editLinkPattern = `${repository.url}/edit/master/docs/:path`;
+
+const commonSidebarConfig: VitePressSidebarOptions = {
+  debugPrint: true,
+  excludePattern: ['CHANGELOG.md'],
+  collapsed: false,
+  capitalizeFirst: true,
+  useTitleFromFileHeading: true,
+  useTitleFromFrontmatter: true,
+  useFolderTitleFromIndexFile: true,
+  sortMenusByFrontmatterOrder: true
+};
+
+const defineSupportLocales = [
+  { label: defaultLocale, translateLocale: defaultLocale },
+  { label: 'ko', translateLocale: 'ko' }
+];
+
+const vitePressConfig: UserConfig = {
+  ...generateI18n({
+    defineLocales: defineSupportLocales,
+    rootLocale: defaultLocale,
+    editLinkPattern: editLinkPattern,
+    searchProvider: 'local'
+  }),
+  title: 'VitePress I18n',
+  lastUpdated: true,
+  outDir: '../docs-dist',
+  cleanUrls: true,
+  metaChunk: true,
+  rewrites: {
+    'en/:rest*': ':rest*'
+  },
+  head: [
+    ['link', { rel: 'icon', type: 'image/png', sizes: '32x32', href: '/logo-32.png' }],
+    ['link', { rel: 'icon', type: 'image/png', sizes: '16x16', href: '/logo-16.png' }],
+    ['link', { rel: 'shortcut icon', href: '/favicon.ico' }]
+  ],
+  sitemap: {
+    hostname: homepage
+  },
+  themeConfig: {
+    logo: { src: '/logo-32.png', width: 24, height: 24 },
+    sidebar: generateSidebar([
+      ...[defaultLocale, 'ko'].map((lang) => {
+        return {
+          ...commonSidebarConfig,
+          documentRootPath: `/docs/${lang}`,
+          resolvePath: defaultLocale === lang ? '/' : `/${lang}/`,
+          ...(defaultLocale === lang ? {} : { basePath: `/${lang}/` })
+        };
+      })
+    ]),
+    socialLinks: [
+      { icon: 'npm', link: 'https://www.npmjs.com/package/vitepress-sidebar' },
+      { icon: 'github', link: repository.url.replace('.git', '') }
+    ],
+    footer: {
+      message: 'Released under the MIT License',
+      copyright: '© <a href="https://cdget.com">CDGet</a>'
+    }
+  }
+};
+
+export default defineConfig(vitePressConfig);

docs/en/guide/getting-started.md

@@ -0,0 +1,72 @@
+---
+order: 1
+---
+
+# 시작하기
+
+이 페이지에서는 VitePress I18n 모듈의 설치 및 사용 방법을 안내합니다.
+
+## 설치
+
+먼저 이 모듈을 사용하기 전에 **[VitePress](https://vitepress.dev)** 모듈을 사전 구성해야 할 수 있습니다.
+
+Node.js 버전은 18.x 이상을 사용하는 것이 좋습니다. **VitePress I18n**은 `ESM`으로 작성되었습니다.
+
+[NPM](https://www.npmjs.com/package/vitepress-i18n) 또는 다른 노드 모듈 패키지 관리자를 사용하여 모듈을 설치할 수 있습니다. 이 패키지는 개발자 환경에서만 사용되므로 `devDependencies`에 설치해야 합니다. 아래 명령어로 설치하세요:
+
+```shell
+# via npm
+$ npm i -D vitepress-i18n
+
+# via yarn
+$ yarn add -D vitepress-i18n
+
+# via pnpm
+$ pnpm i -D vitepress-i18n
+```
+
+## 사용 방법
+
+이 문서에서 VitePress에 대한 기본 지식에 대해서는 설명하지 않습니다. VitePress에 대해 자세히 알아보시려면 다음 사이트를 방문하세요: https://vitepress.dev
+
+먼저 아래 두 가지 방법 중 하나로 `vitepress-i18n`을 import합니다.
+
+### 1. named-import 사용
+
+```javascript
+// `.vitepress/config.js`
+import { generateI18n } from 'vitepress-i18n';
+
+const vitepressI18nOptions = {
+  /* Options... */
+};
+
+export default defineConfig({
+  ...generateI18n(vitepressI18nOptions), // <-- Add this
+  themeConfig: {
+    // ...
+  }
+});
+```
+
+### 2. default-import 사용
+
+```javascript
+// `.vitepress/config.js`
+import VitePressI18n from 'vitepress-i18n';
+
+const vitepressI18nOptions = {
+  /* Options... */
+};
+
+export default defineConfig({
+  ...VitePressI18n.generateI18n(vitepressI18nOptions), // <-- Add this
+  themeConfig: {
+    // ...
+  }
+});
+```
+
+VitePress의 구성 파일인 `.vitepress/config.js` 파일(설정 파일 이름은 프로젝트 환경에 따라 다를 수 있음)의 `defineConfig`의 옵션값의 최상단에 `generateI18n` 메서드를 호출합니다.
+
+이것이 어떻게 출력되는지 테스트하려면 `debugPrint` 옵션을 `true`로 설정하여 VitePress를 빌드해 보세요. 콘솔에 출력이 표시될 것입니다.

docs/en/guide/index.md

@@ -0,0 +1,3 @@
+---
+title: 가이드
+---