CALS

한국어

English

한국어

English

Appearance

시작하기 ​

문서 사이트의 내용을 수정하기 위한 방법들을 기술합니다.

메뉴 추가 및 각 페이지 추가 / 수정을 위해 다음의 사항들에 대해 알아야 합니다.

문서 프로젝트 ​

프로젝트 저장소 위치문서 배포 위치
https://repo.calsplatz.com/CALS/CALS-Forum/guide- 운영 : https://guide.calsplatz.com/
- 개발 : https://review-guide.calsplatz.com/
문서를 생성 / 수정 하기위해 접속하는 사이트생성된 문서가 배포되는 사이트. 배포에 관해서는 배포 문서를 참조하세요.

TIP

문서는 VitPress 를 이용해서 만들어집니다.

계정 생성 ​

상기 GitLab 계정이 있어야만, 문서를 작성할 수 있다. @quintet.co.kr 이메일 계정을 가지고 있는 경우, 회원가입을 통해 계정 생성을 할 수 있다.

유효한 이메일 주소로 계정 생성 한 후, 이메일을 통해 비밀번호를 설정하고 접속할 수 있다.

TIP

@quintet.co.kr 이메일 계정이 없다면, 담당자에게 계정 생성을 요청해야 한다. 이럴 경우 외부계정(External User) 으로 생성된다.
외부계정으로 생성된 계정으로는 오직 초대된 프로젝트에만 접근할 수 있으므로, 프로젝트 초대도 함께 요청해야 한다.

프로젝트 초대 요청 ​

프로젝트 경로로 이동, 또는 Explore 를 통해 CALS / Documentation 프로젝트를 검색하여 이동합니다.

아래의 화면처럼 Request Access 를 통해 프로젝트의 접근을 요청하면, 담당자가 처리 승락 할 경우 가입된 계정으로 이메일이 발송됩니다.

스크린샷

Web IDE 또는 git ​

실제 문서 작업은 GitLab 에서 제공하는 Web IDE 을 통해서 간단히 작업하거나, git 으로 clone 후 로컬에서 작업한 후 push 하는 방식으로 진행 할 수 있습니다.

INFO

프로젝트의 기본 branch 는 develop 입니다.

원격 작업 ​

  • GitLab 프로젝트에서 단축키 . 를 누르면 바로 Web IDE 가 시작됩니다.
  • 화면 왼쪽의 활동바에서 Explorer를 선택하면, 프로젝트의 파일들을 탐색할 수 있습니다.

TIP

Web IDE 에 대한 자세한 사항은 공식 홈페이지를 참조 바랍니다.

TIP

Web IDE 는 기본적으로 Visual Studio Code 와 유사합니다.

로컬 작업 ​

보통의 프로젝트처럼, 아래의 명령으로 저장소를 clone 한 후 작업합니다.

shell
git clone https://repo.calsplatz.com/CALS/CALS-Forum/guide.git

사용하는 에디터에 따라 다음의 링크로 바로 연결 할 수도 있습니다.

TIP

git 에 대한 자세한 사항은 공식 홈페이지를 참조 바랍니다.

INFO

실제 웹사이트에 표시되는 것 처럼 로컬에서 확인해 보려면 Node.js 가 설치되어 있어야 합니다.

Node.js 설치 후,

  • 프로젝트 경로에서 다음의 명령으로 필요 패키지를 설치합니다.
shell
npm install -g pnpm
shell
pnpm i
  • 다음 명령으로 개발모드를 실행합니다.
shell
pnpm docs:dev
  • 아래 결과 처럼 서버가 동작하면 접속하여 확인한다.
console
$ pnpm docs:dev

> @ docs:dev /Users/quintet/Documents/Projects/vite-press-sample
> vitepress dev docs


  vitepress v1.0.0-rc.44

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h to show help

TIP

파일 편집후 저장하면, 자동으로 Reload 된다.

배포 ​

GitLab 의 문서 프로젝트 화면에서 Operate / Environments 메뉴에서 현재 배포된 상태를 확인할 수 있습니다.

메뉴 경로

스크린샷

개발중인 문서의 리뷰 ​

문서 프로젝트는 기본적으로 2개의 브랜치로 구성되어 있습니다.

  • master : 운영 환경의 문서. 작업시 자동 배포
  • develop : 개발 환경의 문서. 작업 후 pipelines 에서 수동 배포 하여 확인 가능.

GitLab 의 문서 프로젝트 화면에서 Build / Pipelines 메뉴에서 모든 빌드 상태를 확인 / 배포할 수 있습니다.

메뉴 경로

스크린샷

develop 브랜치에서 작업 한 후 다음 화면처럼 배포 한 후, environments 에서 Open 하여 확인 할 수 있습니다.

스크린샷

디렉토리 구조 ​

docs ​

문서작성자는 docs 폴더 하위에서만 수정작업이 이루어져야 합니다.

console
/docs
├─ .vitepress
│  └─ config.mts
├─ assets
│  ├─ cals
│  │  └─ images
│  └─ examples
│     └─ images
├─ cals
│  └─ index.md
├─ examples
│  ├─ index.md
│  └─ other files ...
└─ ko
   └─ localized files ...

홈 페이지 ​

홈 페이지의 구성 및 내용을 수정하기 위해서는 /docs/index.md 파일 및 각 언어별 index.md 파일을 수정하여야 합니다.

console
/docs
├─ .vitepress
│  └─ config.mts
├─ assets
│  ├─ cals
│  │  └─ images
│  └─ examples
│     └─ images
├─ cals
│  └─ index.md
├─ examples
│  ├─ index.md
│  └─ other files ...
├─ index.md
└─ ko
   ├─ index.md
   └─ other files ...

TIP

문서의 기본 언어는 영어이며, /docs/index.md 파일은 기본 언어로 표시할 홈페이지를 나타냅니다.

문서 위치와 언어별 문서 ​

문서파일 생성시 아래의 구분에 따라 올바른 경로에 생성하여야 합니다.

프로젝트 구분 ​

cals 와 examples 에는 각각 CALS 사용자 메뉴얼, 메뉴얼 작성을 위한 작업 샘플 문서가 위치합니다.

console
/docs
├─ .vitepress
│  └─ config.mts
├─ assets
│  ├─ cals
│  │  └─ images
│  └─ examples
│     └─ images
├─ cals
│  ├─ index.md
│  └─ other markdown files ...
├─ examples
│  ├─ index.md
│  └─ other markdown files ...
└─ ko
   └─ localized files ...

TIP

index.md 파일은 첫 시작 페이지로, 주소에서 생략 가능합니다.
e.g. https://guide.calsplatz.com/cals/index.html 는 https://guide.calsplatz.com/cals/ 처럼 참조 될 수 있습니다.

WARNING

문서의 기본언어는 영어입니다. 위에서 설명한 문서위치는 기본 언어의 문서 위치이며, 다른 언어를 지원하기 위해서는 다국어을 참고하십시오.

다국어 ​

기본언어인 영어를 각 언어 코드(예. ko) 하위에 프로젝트 구분과 동일한 구조의 문서를 생성합니다.

console
/docs
├─ .vitepress
│  └─ config.mts
├─ assets
│  ├─ cals
│  │  └─ images
│  └─ examples
│     └─ images
├─ cals
│  ├─ index.md
│  └─ other markdown files ...
├─ examples
│  ├─ index.md
│  └─ other markdown files ...
└─ ko
   ├─ cals
   │  └─ korean version markdown files ...
   └─ examples
      └─ korean version markdown files ...

assets ​

이미지 등 기타 리소스 파일을 업로드 하는 폴더. cals 에는 실제 문서에 쓰일 리소스, examples 에는 문서 작성자를 위한 샘플 리소스 파일들을 포함합니다.

console
/docs
├─ .vitepress
│  └─ config.mts
├─ assets
│  ├─ cals
│  │  └─ images
│  └─ examples
│     └─ images
├─ cals
│  ├─ index.md
│  └─ other markdown files ...
├─ examples
│  ├─ index.md
│  └─ other markdown files ...
└─ ko
   └─ localized files ...

config.mts ​

이 파일은 아래와 같은 환경설정이 정의되어 있습니다.

  • 네비게이션 정의
  • 사이드 메뉴 정의
  • 언어 설저 정의
console
/docs
├─ .vitepress
│  └─ config.mts
├─ assets
│  ├─ cals
│  │  └─ images
│  └─ examples
│     └─ images
├─ cals
│  ├─ index.md
│  └─ other markdown files ...
├─ examples
│  ├─ index.md
│  └─ other markdown files ...
└─ ko
   └─ localized files ...

TIP

새로운 페이지를 추가 하기 위해서는, 해당 페이지에 진입할 수 있도록 메뉴를 정의 해야 합니다. 자세한 사항은 페이지 추가 및 메뉴 추가를 참조하십시오.

페이지 추가 ​

위에서 설명한 디렉토리 구조에 따라 작성할 페이지를 생성합니다. 아래의 규칙을 지키는 파일명으로 생성하는것이 좋습니다.

  • 파일명은 모두 영어 소문자
  • 언더바(_) 보다는 하이픈(-)
  • 확장자는 Markdown 형식인 .md
  • 다국어를 지원하는 경우, 경로(path)에 주의해야함

TIP

필요에 따라 하위 폴더를 생성하는것이 좋을 수 있습니다.

Web IDE 에서 파일 생성하기
  1. 왼쪽 활동바 영역에서 Explorer 선택.
  2. 대상 경로 선택 후 New File... 선택. 스크린샷
  3. 생성될 파일명 입력. ⏎스크린샷

이미지 첨부

이미지를 첨부하고 싶다면 그림 항목을 참조하세요.

CAUTION

  • 다국어를 지원하는 경우, 서로 다른 이미지가 필요할 수도 있습니다.
  • 기본 언어의 페이지와 다국어 페이지는 경로가 다르기 때문에 이미지 참조 경로도 달라집니다.
    (../../ 와 ../ 처럼 상위 경로가 다를 수 있음)

페이지 수정

각 페이지 하단에 Edit this page 버튼을 클릭하면 Web IDE 로 바로 연결됩니다. 스크린샷

TIP

Notion을 이용하여 복사/붙여넣기 하면 쉽게 Markdown 으로 변환 할 수 있다.

메뉴 추가 ​

문서 왼쪽에 표시되는 메뉴를 수정하기 위해서는 config.mts 파일을 수정해야 한다.

JSON 객체에서 경로는 themeConfig.sidebar[.items] 에 해당 메뉴를 추가 할 수 있다.

예제
typescript
export default defineConfig({
  lang: "en-US",
  title: "CALS",
  description: "A CALS Documentation site.",
  lastUpdated: true,
  themeConfig: {           
    i18nRouting: true,
    socialLinks: [
      { icon: "facebook", link: "https://www.facebook.com/quintetsystems" },
      {
        icon: "instagram",
        link: "https://www.instagram.com/quintetsystems_main",
      },
      {
        icon: "youtube",
        link: "https://www.youtube.com/channel/UC8VZ6prUQFOxjBiU5guBwkg",
      },
      {
        icon: "github",
        link: "https://repo.calsplatz.com/CALS/CALS-Forum/guide",
      },
    ],
    editLink: {
      pattern:
        "https://repo.calsplatz.com/-/ide/project/CALS/CALS-Forum/guide/edit/develop/-/docs/:path",
    },
    footer: {
      copyright: "Copyright © 2019-present Quintet Systems.",
    },
    siteTitle: "CALS",
    nav: [
      { text: "Home", link: "/" },
      { text: "Docs", link: "/cals/" },
      { text: "Examples", link: "/examples/" },
      {
        text: "Web IDE",
        link: "https://repo.calsplatz.com/-/ide/project/CALS/CALS-Forum/guide/edit/develop/-/",
      },
    ],
    sidebar: [                
      {
        text: "CALS Documentation",
        items: [
          {
            items: [          
               { text: "Getting Started", link: "/cals/" },
               { text: "New Page", link: "/cals/new-page" },   
            ],
          },
        ],
      },
      {
        text: "Documentation Examples",
        items: [
          {
            items: [
              { text: "Getting Started", link: "/examples/" },
              { text: "Title", link: "/examples/title" },
              { text: "Content", link: "/examples/content" },
              { text: "Image", link: "/examples/image" },
              { text: "Table", link: "/examples/table" },
            ],
          },
        ],
      },
    ],
    search: {
      provider: "local",
      options: {
        detailedView: true,
      },
    },
    outline: "deep",
  },
typescript
  locales: {                     
    root: {
      label: "English",
      lang: "en",
    },
    ko: {                        
      label: "한국어",
      lang: "ko",
      themeConfig: {             
        i18nRouting: true,
        siteTitle: "CALS 문서",
        nav: [
          { text: "홈", link: "/" },
          { text: "CALS 문서", link: "/ko/cals/" },
          { text: "문서 작성 예제", link: "/ko/examples/" },
          {
            text: "Web IDE",
            link: "https://repo.calsplatz.com/-/ide/project/CALS/CALS-Forum/guide/edit/develop/-/",
          },
        ],
        sidebar: [               
          {
            text: "CALS 문서",
            items: [
              {
                items: [         
                  { text: "시작하기", link: "/ko/cals/" },
                  { text: "새 페이지", link: "/ko/cals/new-page" },   
                ],
              },
            ],
          },
          {
            text: "문서 작성 예제",
            items: [
              {
                items: [
                  { text: "시작하기", link: "/ko/examples/" },
                  { text: "제목", link: "/ko/examples/title" },
                  { text: "글", link: "/ko/examples/content" },
                  { text: "그림", link: "/ko/examples/image" },
                  { text: "표", link: "/ko/examples/table" },
                ],
              },
            ],
          },
        ],
        search: {
          provider: "local",
          options: {
            detailedView: true,
            translations: {
              button: { buttonText: "검색", buttonAriaLabel: "검색" },
            },
          },
        },
        outline: { level: "deep", label: "이 페이지의 내용" },
      },
    },
  },
});

WARNING

기본 언어와 다국어는 각각 별도 페이지가 작성되며, 경로가 다르다.

TIP

설정에 대한 더 자세한 사항은 VitePress 문서를 참조.

Copyright © 2019-present Quintet Systems.