이 가이드는 리포지터리 소스 코드 뷰어에서 구문 강조를 구현하는 모범 사례와 세부 구현 방법을 설명합니다. GitLab은 두 가지 구문 강조 라이브러리를 사용합니다:

• 소스 뷰어에서 클라이언트 측 강조를 위한 Highlight.js

지원 언어 전체 목록을 참조하세요.

• 서버 측 폴백으로 사용되는 Rouge

지원 언어 전체 목록을 참조하세요.

소스 코드 뷰어는 이 두 가지 방식을 함께 사용하여 다양한 언어를 지원하고 리포지터리에서 파일을 볼 때 최적의 성능을 보장합니다.

컴포넌트 개요#

구문 강조 구현은 다음과 같은 주요 컴포넌트로 구성됩니다:

• blob_content_viewer.vue: 파일 콘텐츠를 표시하는 메인 컴포넌트

• source_viewer.vue: 소스 코드 렌더링을 처리하는 컴포넌트

• highlight_mixin.js: 강조 처리 및 WebWorker 통신을 관리하는 컴포넌트

• highlight_utils.js: 콘텐츠 청크 분할 및 처리를 위한 유틸리티를 제공하는 컴포넌트

성능 원칙#

콘텐츠를 최대한 빠르게 표시하기#

단계적 렌더링 방식을 통해 콘텐츠 표시를 최적화합니다:

• 처음 70줄을 일반 텍스트로 즉시 렌더링합니다(강조 없이).

• WebWorker에 처음 70줄의 강조 처리를 요청합니다.

• WebWorker에 전체 파일의 강조 처리를 요청합니다.

최적의 브라우저 성능 유지하기#

최적의 브라우저 성능을 유지하기 위해:

• 메인 스레드를 차단하지 않도록 강조 작업에 WebWorker를 사용합니다.

• 강조된 콘텐츠를 청크로 나누고 IntersectionObserver API를 사용하여 사용자가 스크롤할 때 렌더링합니다.

구문 강조 지원 추가하기#

다음 방법으로 새로운 언어에 대한 구문 강조 지원을 추가할 수 있습니다:

• 기존 서드파티 언어 정의 사용.

• 코드베이스에 커스텀 언어 정의 생성.

선택하는 방법은 해당 언어에 Highlight.js 호환 정의가 이미 있는지 여부에 따라 달라집니다.

서드파티 정의가 있는 언어의 경우#

package.json에 서드파티 의존성을 추가하고 highlight_js_language_loader에서 해당 의존성을 import할 수 있습니다.

예시:

• package.json에 의존성 추가:

// package.json

//...
  "dependencies": {
    "@gleam-lang/highlight.js-gleam": "^1.5.0",
//...

• highlight_js_language_loader.js에서 언어 import:

// highlight_js_language_loader.js

//...
  gleam: () => import(/* webpackChunkName: 'hl-gleam' */ '@gleam-lang/highlight.js-gleam'),
//...

언어가 여전히 일반 텍스트로 표시된다면 highlight_mixin.js에서 파일 확장자 기반의 언어 감지를 추가해야 할 수 있습니다:

if (name.endsWith('.gleam')) {
  language = 'gleam';
}

기존 정의가 없는 언어의 경우#

새로운 언어 정의는 ~/vue_shared/components/source_viewer/languages/ 하위의 코드베이스에 추가할 수 있습니다.

새로운 언어 지원을 추가하려면:

• Highlight.js 문법을 따라 새 언어 정의 파일을 생성합니다.

• highlight_js_language_loader.js에 언어를 등록합니다.

• 필요한 경우 highlight_mixin.js에 파일 확장자 매핑을 추가합니다.

다음은 커스텀 언어 구현의 두 가지 예시입니다:

• Svelte

• CODEOWNERS