---
title: 콘텐츠 작성 표준 가이드
sidebar:
  order: 0
---


본 문서는 **Civil Engineering Lab**의 자료를 작성할 때 준수해야 할 **기능적 규칙**과 **내용 작성 가이드**를 정의합니다. 모든 작성자는 이 기준을 따라 문서를 작성해 주시기 바랍니다.

---

## 1. 개요 및 작성 표준
**C.E.L**의 기본 구조 및 통일된 콘텐츠를 만들기 위해 콘텐츠 작성시 지켜야 하는 사항을 설명합니다. 

### 1.1 디렉토리 구조 및 파일명

C.E.L은 폴더 구조가 곧 **카테고리**가 되는 방식을 따릅니다.

**폴더 구조도**
```text
src/
├── assets/
│   └── images/                  # [이미지 저장소]
│
└── content/
    └── docs/                    # [문서 저장소] .mdx 파일은 여기에 위치합니다
        ├── 작성 가이드.mdx
        ├── Civil DX/            # [상위 탭] 콘텐츠를 구분하는 가장 큰 범주입니다.
        │   ├── BIM,DX의 이해/        # 폴더를 만들면 '카테고리'가 됩니다
        │   │   ├── 01. 개념 정의.mdx     # 각 콘텐츠는 파일형태로 작성/저장됩니다.
        │   │   └── 02. DX의 목표.mdx
        │   ├── Civil DX 소개/
        └── 기반기술/
```

**계층별 명명 규칙**

* **상위 탭 (1단계 폴더)**
   * `docs/` 바로 아래에 위치하는 폴더입니다.
   * 사이드바의 가장 큰 탭이 되며, **이름(한글/영문)** 으로만 작성합니다. (번호 X)
   * 예시: `Civil DX`, `기반기술`

* **카테고리 (2단계 폴더)**
   * 상위 탭 아래에 위치하는 폴더입니다.
   * 관련된 문서들을 묶어주는 그룹 역할을 하며, **이름(한글/영문)** 으로만 작성합니다.
   * 예시: `BIM,DX의 이해`, `Civil DX 소개`

* ** 콘텐츠 (파일)**
   * 실제 내용이 담긴 `.mdx` 파일입니다.
   * 하나의 파일은 하나의 주제를 다루며, **이름(한글/영문)** 으로만 작성합니다.
   * 예시: `개념 정의.mdx`, `DX의 목표.mdx`

<br/>

### 1.2 문체 및 용어

콘텐츠의 객관성과 신뢰도를 높이기 위해, 감정을 배제한 **평어체(설명조)** 형식을 사용합니다. 여러 작성자가 작성하더라도 마치 한 사람이 쓴 것처럼 일관성을 유지하는 것이 목표입니다.

**문체 가이드**

* **1. 문장 끝맺음 (종결어미)**
   * 모든 문장은 **'~다', '~한다', '~된다'**로 명확하게 끝맺습니다.
   * 존댓말(~입니다, ~해요)이나 구어체(~죠, ~네요)는 사용하지 않습니다.
       * **Bad**: 버튼을 누르면 설정이 완료돼요. / 완료됩니다.
      * **Good**: 버튼을 눌러 설정을 완료한다.

* **객관적 서술 (No 추측)**
   * 개인적인 의견이나 불확실한 추측(~인 것 같다, ~보인다)은 지양합니다.
   * 근거에 기반하여 단정적인 어조를 사용합니다.
       * **Bad**: A 방식이 더 효율적인 것 같다.
      * **Good**: A 방식이 시간 단축 측면에서 더 효율적이다.

* **간결한 문장**
   * 한 문장이 2줄을 넘어가지 않도록 짧게 끊어서 작성합니다.

**용어 표기 원칙**

* **전문 용어 표기**
   * 문서에서 처음 등장하는 핵심 용어는 **'한글(영문/약어)'** 형태로 병기합니다.
   * 이후 반복될 때는 약어만 사용해도 무방합니다.
       * *예시*: 처음에는 **디지털 전환(DX)** 으로 표기하고, 이후에는 **DX**로 표기.

* **외래어 표기**
   * 널리 통용되는 외래어는 한글 표기를 원칙으로 하되, 괄호 안에 원어를 적어 명확히 합니다.
   * 단, 메뉴명이나 코드 변수는 영문 그대로 작성합니다.
       * *예시*: **데이터베이스(Database)**, **인터페이스(Interface)**
       * *예시*: `config.json` 파일, `User` 클래스

**작성 예시 비교**

| 구분 | 잘못된 예시 (Bad) ❌ | 올바른 예시 (Good) ✅ |
| :--- | :--- | :--- |
| **어조** | BIM은 정말 중요한 기술입니다. | BIM은 건설 산업의 핵심 기술이다. |
| **지시** | 여기서 저장 버튼을 누르세요. | 저장 버튼을 눌러 변경 사항을 저장한다. |
| **용어** | Data를 관리하는 게 중요해요. | 데이터(Data) 관리의 중요성이 강조된다. |

---

<br/>

## 2. 본문 구조 및 목차

본문의 구조는 **헤더(Headings)** 태그(`##`)를 통해 결정됩니다. 헤더를 올바르게 작성해야 **우측 목차**가 자동으로 생성되어 열람자가 내용을 쉽게 파악할 수 있습니다.

### 2.1 문서 설정

문서의 **가장 첫 줄**에는 반드시 페이지의 정보를 담은 프론트매터(Frontmatter)를 작성해야 합니다.

```yaml
---
title: 페이지 제목 # 화면 최상단 및 좌측 카테고리에 표시
sidebar:
  order: 10   # 좌측 카테고리 순서 (숫자가 낮은 순서대로 표시됨)
---
```

### 2.2 제목 및 목차 계층 구조

우측 목차(On this page)는 **H2(`##`)부터 H3(`###`)까지** 수집하여 표시합니다. 문서의 구조를 쉽게 파악할 수 있도록 **번호 매기기**를 권장하며, 각 헤더의 역할과 목차 표시 여부는 아래와 같습니다.

| 마크다운 | 레벨 | 번호 규칙 | 목차 표시 | 역할 |
| :--- | :--- | :--- | :---: | :--- |
| `#` | **H1** | (사용 금지) | **X (미표시)** | **문서 제목** (Frontmatter `title`로 대체) |
| `##` | **H2** | **1**, **2** | **O (1단계)** | **대주제** (가장 큰 챕터) |
| `###` | **H3** | **1.1**, **1.2.** | **O (2단계)** | **중주제** (하위 섹션) |
| `####` | **H4** | **1.1.1**, **1.1.2** | **O (3단계)** | **소주제** (본문 내 상세 설명용) |


:::danger[작성 금지 사항]
1. **`#` (H1) 사용 금지**: 페이지 제목은 자동으로 생성되므로 본문에 쓰지 않습니다.
2. **단계 건너뛰기 금지**: `##`(1.) 없이 바로 `###`(1.1.)을 사용하면 목차 구조가 틀어집니다.
:::

<br/>
**[제목 구조 예시]**
```markdown
## 1. DX에 대한 인식 (H2)

### 1.1 국내 인식 (H3)

#### 1.1.1 발주처의 인식 (H4)

```


<br/>
### 2.3 문단 및 줄 바꿈

마크다운으로 콘텐츠 작성시 엔터키 한 번으로는 줄이 바뀌지 않습니다. 상황에 따라 아래 두 가지 방법을 구분해서 사용하세요.

* **문단 나누기** : 내용의 호흡이 바뀔 때는 **빈 줄(Enter 2번)** 을 넣어 확실하게 띄웁니다.  
* **단순 줄 바꾸기** : 같은 문단 안에서 줄만 바꿀 때는 문장 끝에 **공백 2칸(Space bar)** 을 입력합니다.
<br/>
**[문단 바꿈 작성 예시]**
```markdown
1. 엔터를 한 번만 쳤을 때 (줄바꿈 X)
윗줄 내용입니다.
아랫줄 내용입니다.
-> 결과: 한 줄로 쭉 이어져서 나옵니다.

2. 문단을 나눌 때 (Enter 2번)
윗줄 내용입니다.

아랫줄 내용입니다.
-> 결과: 위아래 간격이 넓게 벌어집니다.
```
<br/>
**[줄바꿈 작성 예시]**
```markdown
1. 줄만 바꿀 때 (Space 2번)
윗줄 내용입니다.  (여기 뒤에 공백 2칸 있음)
아랫줄 내용입니다.
-> 결과: 간격 없이 바로 아랫줄로 내려갑니다.
```
<br/>
### 2.4 목록 
내용을 나열할 때는 기호나 숫자를 사용하여 가독성을 높일 수 있습니다.

- 순서 없는 목록 : - (하이픈) 또는`*`(별표)를 사용합니다.
- 순서 있는 목록 : `1.`과 같이 숫자와 점을 사용합니다.(제목과 달리 본문 크기로 적용됩니다.)
- 하위 목록(들여쓰기) : `Tab`키를 눌러 들여쓰기 합니다.

<br/>
**[목록 작성 예시]**
```markdown
1. 주요 공정 (Space 2번)
    - (Tab) 터파기
    - (Tab) 기초 타설
```
> **[적용 예시]**
> 1. 주요 공정 (Space 2번)
>   - (Tab) 터파기
>   - (Tab) 기초 타설
<br/>
### 2.4 주제 구분
내용의 흐름이 크게 바뀌거나 섹션을 시각적으로 분리할 때 사용합니다.

* **사용법**: 빈 줄에 하이픈 3개(`---`)를 입력합니다.
* **사용처**: `##`등 내용이 바뀔 때 사용합니다 `---`이후에 `<br/>`을 넣어 주제간 공백을 둡니다.
* **주의사항**: 위아래로 **빈 줄**을 두어야 선이 깔끔하게 그려집니다.

**[가로선 작성 예시]**

```markdown
이전 주제에 대한 설명이 끝났습니다.

---
(가로선이 생기며 내용이 분리됩니다)

여기서부터는 새로운 주제입니다.

---
```
---
<br/>


## 3. 텍스트 서식 및 컴포넌트

글자의 모양을 꾸미거나(기초), 박스 및 탭 기능(심화)을 사용하여 콘텐츠를 보기 좋게 구성하고 강조하고 싶은 핵심을 쉽게 전달할 수 있습니다.

### 3.1 기초 텍스트 서식 (Basic Formatting)

가장 자주 사용되는 글자 강조 규칙입니다. 문장 내에서 중요한 키워드나 용어를 돋보이게 할 때 사용합니다.

* **굵게 (Bold)**: 별표 2개(`**`)로 감쌉니다. 핵심 키워드를 강조할 때 사용합니다.
* **기울임 (Italic)**: 별표 1개(`*`)로 감쌉니다. 용어의 영문 표기나 이미지 캡션에 주로 사용합니다.
* **취소선 (Strikethrough)**: 물결표 2개(`~~`)로 감쌉니다. 변경 전 내용을 남겨두거나 삭제됨을 표현할 때 사용합니다.
* **인라인 코드 (Inline Code)**: 백틱 1개(`)로 감쌉니다. 문장 중간에 명령어, 파일명, 단축키, 변수명 등을 언급할 때 사용합니다.

**[작성 예시]**

```markdown
1. **스타일 예시**
   이것은 **매우 중요한 내용**입니다.
   이것은 *보조 설명(Comment)*입니다.
   이것은 ~~삭제된 내용~~입니다.

2. **인라인 코드 예시**
   저장하려면 `Ctrl + S` 키를 누르세요.
   설정 파일은 `config.json`입니다.
```
> **[적용 예시]**
> 1. **스타일 예시**  
>    이것은 **매우 중요한 내용**입니다.  
>    이것은 *보조 설명(Comment)* 입니다.  
>    이것은 ~~삭제된 내용~~입니다.  
>
> 2. **인라인 코드 예시**  
>    저장하려면 `Ctrl + S` 키를 누르세요.  
>    설정 파일은 `config.json`입니다.  

<br/>

### 3.2 인용 및 특수기호

문단 전체를 인용하거나, 문법 기호를 글자 그대로 표현할 때 사용합니다

* **인용문**: 문장 맨 앞에 `>`(부등호)를 붙입니다.
* **위첨자/아래첨자**: `<sup>`(위), `<sub>`(아래)를 사용해서 단위나 화학식을 표현할 수 있습니다.
* **이스케이프**: 마크다운 기호(*,#,[ 등)를 서식 기능 없이 글자 그대로 보여주려면 앞에 역슬래시 `\`를 붙입니다.




**[작성 예시]**
```
1. **인용문 예시**
   > "디지털 전환은 선택이 아닌 필수다."

2. **첨자 예시**
   아파트 면적은 84m<sup>2</sup>이고, 물의 성분은 H<sub>2</sub>O입니다.

3. **이스케이프 예시**
   별표 기호를 강조 없이 쓰려면 \*\*이렇게\*\* 작성합니다.
```

> **[적용 예시]**
> 1. **인용문 예시**
>   > "디지털 전환은 선택이 아닌 필수다."
>
>2. **첨자 예시**
>   아파트 면적은 84m<sup>2</sup>이고, 물의 성분은 H<sub>2</sub>O입니다.
>
>3. **이스케이프 예시**
>   별표 기호를 강조 없이 쓰려면 \*\*이렇게\*\* 작성합니다.

<br/>

### 3.3 텍스트 박스 및 강조

본문과 구분되는 박스를 만들거나, 문장 중간에 특정 단어를 강조할 때 사용합니다. 

* **한 단어 강조 (Inline)**
문장 중간에 짧은 내용을 강조할 때 사용합니다. 숫자 1 옆에 있는 **백틱(`)** 기호 1개로 감쌉니다.
   * **용도**: 파일명, 메뉴 이름, 키보드 단축키, 강조하고 싶은 짧은 값
<br/>
* **박스 강조 (Block)**
여러 줄의 내용을 박스 안에 담아 보여줄 때 사용합니다. 위아래를 **백틱 3개(` ``` `)** 로 감쌉니다.
   * **용도**: 파일의 전체 내용, 폴더 구조, 복사해야 할 텍스트 데이터
   * **제목 달기**: 첫 줄 언어 이름 뒤에 `title="제목"`을 적으면 박스 위에 이름표가 붙습니다.

**[작성 예시]**

```markdown
1. **한 단어 강조**
   설정 파일은 `config.txt`에 저장됩니다. 저장하려면 `Ctrl + S`를 누르세요.

2. **박스 강조**
```text title="공사개요.txt"
프로젝트명: 교량 건설공사
착공일: 2026-01-02
담당자: 김토목 과장
위치: 서울특별시 ...
```

> **적용 예시**
> 1. **한 단어 강조**
>    설정 파일은 `config.txt`에 저장됩니다. 저장하려면 `Ctrl + S`를 누르세요.
>
> 2. **박스 강조**
>    ```text title="공사개요.txt"
>    프로젝트명: 교량 건설공사
>    착공일: 2026-01-01
>    담당자: 김토목 과장
>    위치: 서울특별시 ...
>    ```

<br/>

### 3.4 안내 박스

글을 읽는 도중 독자의 주의를 환기시키거나, 팁을 줄 때 사용합니다. 별도의 설정 없이 바로 사용할 수 있습니다.

* **사용법**: 내용의 시작과 끝을 `:::` (콜론 3개)로 감쌉니다.
* **종류**: `note`(참고), `tip`(팁), `caution`(주의), `danger`(경고) 4가지가 있습니다.
* **제목 설정**: `:::tip[여기에 제목 입력]` 형식으로 대괄호 안에 제목을 변경할 수 있습니다.

**[작성 예시]**

```markdown
:::note[참고]
이 내용은 본문과 직접적인 관련은 없지만 알아두면 좋은 배경지식입니다.
:::

:::tip[작업 팁]
작성도중 결과물을 확인하는 습관을 들이세요.
:::

:::caution[주의 사항]
파일명을 변경하면 기존에 연결된 링크가 끊어질 수 있습니다.
:::

:::danger[삭제 경고]
이 버튼을 누르면 데이터가 영구적으로 삭제되며 복구할 수 없습니다.
:::

```
>**적용 예시**
>:::note[참고]
>이 내용은 본문과 직접적인 관련은 없지만 알아두면 좋은 배경지식입니다.
>:::
>
>:::tip[작업 팁]
>작성도중 결과물을 확인하는 습관을 들이세요.
>:::
>
>:::caution[주의 사항]
>파일명을 변경하면 기존에 연결된 링크가 끊어질 수 있습니다.
>:::
>
>:::danger[삭제 경고]
>이 버튼을 누르면 데이터가 영구적으로 삭제되며 복구할 수 없습니다.
>:::

<br/>

### 3.5 링크

문서 간의 연결이나 외부 참고 자료를 명시할 때 사용합니다.

* **내부 링크 (Internal)**: 같은 사이트 내 다른 문서로 이동할 때는 **상대 경로**(`../`, `./`)를 사용합니다. 파일 확장자(`.mdx`)는 생략 가능합니다.
* **외부 링크 (External)**: 다른 웹사이트로 이동할 때는 **전체 URL**(`https://...`)을 입력합니다.

**작성 예시**

```markdown
* **내부 링크**: [BIM의 정의 보러가기](../01-basic-concept)
* **외부 링크**: [건설기술연구원 홈페이지](https://www.kict.re.kr)
```
**적용 예시**
* **내부 링크**: [BIM의 정의 보러가기](../01-basic-concept)
* **외부 링크**: [건설기술연구원 홈페이지](https://www.kict.re.kr)

<br/>
---
<br/>

## 4. 시각 자료 및 수식

콘텐츠 작성시 필요한 이미지, 도표, 수식 등의 작성 규칙을 정의합니다.

### 4.1 이미지

모든 이미지 파일은 프로젝트의 `assets/images/` 경로에 저장한 후 불러옵니다.

* **파일 경로**: `/assets/images/[파일명]`
* **캡션**: 이미지 바로 아래 줄에 `기울임꼴`로 설명을 작성하여 캡션처럼 보이게 합니다.

**작성 예시**

```markdown
![BIM 성숙도 단계](assets/images//bim-maturity.png)
*<그림 1> BIM 성숙도 4단계 모델*
```

<br/>

### 4.2 표

데이터를 행과 열로 정리하여 보여줄 때 사용합니다. 마크다운 표는 **파이프 기호(`|`)**로 칸을 나누고, **하이픈(`-`)**으로 헤더(제목줄)를 구분하여 작성합니다.

#### 4.2.1 기본 구조 만들기
표를 만드는 3단계 순서입니다.

1.  **기둥 세우기**: `|` (Shift + 원화표시/백슬래시) 기호를 사용하여 열을 구분합니다.
2.  **헤더 구분하기**: 첫 번째 줄(제목) 바로 아래에 `| --- | --- |` 처럼 하이픈을 넣어 제목줄과 본문을 나눕니다.
3.  **내용 채우기**: 그 아래로 데이터를 입력합니다.

#### 4.2.2. 정렬 방식 설정
두 번째 줄(구분선)에 **콜론(`:`)**을 어디에 찍느냐에 따라 글자 정렬이 달라집니다.

* **왼쪽 정렬** (기본값): `:---` (콜론을 왼쪽에) → *텍스트에 적합*
* **가운데 정렬**: `:---:` (콜론을 양쪽에) → *짧은 단어, 상태 표시에 적합*
* **오른쪽 정렬**: `---:` (콜론을 오른쪽에) → *숫자, 금액 데이터에 적합*

#### 4.2.3 표 안에서 줄바꿈
표의 셀 안에서는 엔터키로 줄을 바꿀 수 없습니다. 반드시 **HTML 태그 `<br/>`**를 입력해야 줄이 바뀝니다.

**작성 예시**

```markdown
| 구분(가운데) | 설명(왼쪽) | 비고(오른쪽) |
| :---: | :--- | ---: |
| **BIM** | 3차원 형상 정보 중심 | 100% |
| **DX** | 데이터 기반 의사결정<br/>(프로세스 혁신) | 50% |

```
> **적용 예시**
> | 구분(가운데) | 설명(왼쪽) | 비고(오른쪽) |
> | :---: | :--- | ---: |
> | **BIM** | 3차원 형상 정보 중심 | 100% |
> | **DX** | 데이터 기반 의사결정<br/>(프로세스 혁신) | 50% |

<br/>

### 4.3 수식
공학 공식이나 변수는 **KaTeX** 문법을 사용하여 표현합니다.

* **인라인 수식 (Inline)**: 문장 중간에 변수나 짧은 식을 넣을 때는 `$` (달러 기호 1개)로 감쌉니다.
* **블록 수식 (Block)**: 별도의 줄에 수식을 크게 강조할 때는 `$$` (달러 기호 2개)로 감쌉니다.


**KaTeX 수식**

```markdown
인라인 수식: $E = mc^2$
블록 수식:
  $$
  \int_{-\infty}^{\infty} e^{-x^2} \, dx = \sqrt{\pi}
  $$
```
> **적용 예시**  
> - 인라인 수식: $E = mc^2$
> - 블록 수식:
>
>  $$
>  \int_{-\infty}^{\infty} e^{-x^2} \, dx = \sqrt{\pi}
>  $$

<br/>

```
복잡한 매크로나 패키지는 KaTeX에서 지원되지 않을 수 있으니,   
반영 후 오류가 발생하면 대체 표기나 단순화된 수식을 사용하기 바랍니다.
```

:::note[참고]
* [**LaTex 문법**](https://katex.org/docs/supported.html)

:::