CALS

English

한국어

English

한국어

Appearance

Getting Started ​

Describes methods for modifying the content of the document site.

To add menus and add/edit each page, you need to know the following:

Documentation Project ​

Project Repository LocationDocument Distribution Location
http://repo.calsplatz.com/CALS/CALS-Forum/guide- Production : https://guide.calsplatz.com/
- Development : https://review-guide.calsplatz.com/
Site for accessing to create / edit documentsA site where created documents are distributed. For deployment information, please refer to the (#deploy) documentation.

TIP

Documents are created using VitePress

Account Creation ​

The above GitLab account is required to write documents. If you have an @quintet.co.kr email account, you can create an account through registration.

After creating an account with a valid email address, you can set a password via email and log in.

TIP

If you do not have an @quintet.co.kr email account, you need to request account creation from the administrator. In this case, it will be created as an external user account. With an account created as an external user, you can only access invited projects, so you need to request project invitations as well.

Request a project invitation ​

Navigate to the project path or use Explore to search for the CALS / Documentation project and navigate to it.

Once there, click on Request Access as shown below to request access to the project. If approved by the administrator, an email will be sent to your registered account.

Request Access

Web IDE or git ​

Actual document work can be done either through the Web IDE provided by GitLab for simple editing or by using git to clone the repository locally, make changes, and then push them.

INFO

The default branch of the project is develop.

Remote Work ​

  • Pressing . on the GitLab project will directly start the Web IDE.
  • Selecting Explorer from the left activity bar allows you to navigate through the project files.

TIP

For more details about the Web IDE, refer to the official documentation.

TIP

The Web IDE is essentially similar to Visual Studio Code.

Local Work or Developing the project locally ​

As usual projects, you just need to clone the project and start working on the project locally.

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

Depending on the editor you use, you may be able to connect directly to the following link.

TIP

For more information about git, please refer to official website.

INFO

To view it locally as it appears on the actual website, Node.js must be installed. After installing Node.js ,

  • Install the required packages using the following command from the project path.
shell
npm install -g pnpm
shell
pnpm i
  • Run development mode with the following command:
shell
pnpm docs:dev
  • If the server operates as shown below, connect and check.
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

If you save the file after editing, it will automatically Reload.

Deployment ​

You can check the current deployment status on the Operate / Environments menu on the documentation project screen in GitLab.

Menu Path

Screenshot

Reviewing Documents in Progress ​

The documentation project is composed of two main branches:

  • master : Documents for the production environment. Automatically deployed during work.
  • develop : Documents for the development environment. Manually deployable via pipelines after work for verification.

You can check all build statuses and deployments on the Build / Pipelines menu on GitLab's documentation project screen.

Menu Path

Screenshot

After working on the develop branch and deploying, you can check the deployed document by clicking Open on environments as shown below:

Screenshot

Directory Structure ​

docs ​

Documentation Authors should only make modifications under the docs folder.

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

Home page ​

To modify the structure and content of the homepage, edit the /docs/index.md file and index.md file for each language.

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

The default language of the document is English, and the /docs/index.md file represents the homepage displayed in the default language.

Document Location and Language-Specific Documents ​

When creating document files, they should be placed in the correct path according to the following distinctions.

Project Classification ​

The cals and examples directories contain documents for the CALS User Manual and Sample Work for Manual Writing, respectively.

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

The index.md file serves as the initial landing page and can be omitted from the URL. For example, https://guide.calsplatz.com/cals/index.html can be referenced as https://guide.calsplatz.com/cals/.

WARNING

The default language of the document is English. The document locations described above are for the default language, and to support other languages, please refer to Multilingual.

Multilanguage Support ​

Create a document with the same structure as Project Division under each language code (e.g. ko) in English, the default language.

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 ​

Folder for uploading images and other resource files.
CALS contains resources used in actual documents, while examples contains sample resource files for document authors.

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 ​

This file defines the following configurations:

  • Navigation definitions
  • Sidebar menu definitions
  • Language settings definitions
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

To add a new page, you need to define a menu so that the page can be accessed. For more details, refer to Adding a Page(#new-page) and Adding a Menu (#new-menu).

Adding Page ​

Create the page following the Directory Structure described above. It is recommended to follow these rules for the filename:

  • All lowercase letters in English
  • Hyphens (-) rather than underscores (_)
  • Markdown format with the extension .md
  • Pay attention to the path if supporting multiple languages

TIP

It may be helpful to create subfolders as needed.

File Creation in Web IDE
  1. Select Explorer in the left activity bar area.
  2. Choose the target path and select New File.... Screenshot
  3. Enter the desired file name and press ⏎. Screenshot

Image Attachment

If you want to attach an image, refer to the Image section.

CAUTION

  • In multilingual support cases, different images might be needed.
  • Since the default language page and multilingual pages have different paths, the image reference paths may also differ. (e.g., ../../ and ../ for different parent paths)

Page Modification

Clicking the Edit this page button at the bottom of each page takes you directly to the Web IDE. Screenshot

TIP

Notion can easily convert your content to Markdown format through copy/paste.

Adding a new menu ​

To modify the menu displayed on the left side of the document, you need to edit the config.mts file.

In the JSON object, the path is themeConfig.sidebar[.items], where you can add the desired menu items.

Example
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: "http://repo.calsplatz.com/CALS/CALS-Forum/guide",
      },
    ],
    editLink: {
      pattern:
        "http://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: "http://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: "http://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

The default language and multilingual versions are each written on separate pages, and they have different paths.

TIP

For more details on settings, see VitePress documentation.

Copyright © 2019-present Quintet Systems.