문서의 분류, 하드디스크 저장 위치, 버전 관리, 그리고 판매 링크 관리까지 한 번에 체계화

 

 

🅿️ 제가 작성한 문서가 많습니다. 업데이트도 꾸준히 합니다. 판매도 합니다. 이런 문서들을 분류하고, 하드디스크에서 위치를 관리하고, 버전을 관리하는 효율적인 방법을 제안하세요. 

 

전자책, 기술 가이드북, 교육 자료처럼 작성량이 많고, 주기적으로 업데이트되며, 판매까지 이루어지는 문서는 단순히 폴더 몇 개로 관리하려 하면 금방 수많은 '최종_진짜최종.pdf' 파일들로 꼬이게 됩니다.

 

문서의 분류, 하드디스크 저장 위치, 버전 관리, 그리고 판매 링크 관리까지 한 번에 체계화할 수 있는 4단계 워크플로우를 제안해 드립니다. 

 

1. 하드디스크 폴더 구조 체계화 (디렉터리 설계)

하드디스크에는 문서의 상태(Draft/Published/Sales)와 ID를 기준으로 폴더를 고정해야 파일이 섞이지 않습니다.

Plaintext

 

D:\Workspaces\
└── 01_Docs_Product/
    └── [카테고리명]/                   # 예: 01_IoT_Hardware, 02_Firmware
        └── [문서ID]_[문서영문약어]/    # 예: PRD-001_ESP32_Guide
            ├── 01_Src/                 # 원본 문서 (Word, Markdown, KiCad 등)
            ├── 02_Assets/              # 이미지, 회로도, 다이어그램, 예제 코드
            ├── 03_Builds/              # 배포용 결과물 (PDF, EPUB, ZIP)
            └── 04_Marketing/           # 썸네일, 상세페이지 이미지, 문구

핵심 팁 (문서 ID 도입):

모든 판매용 문서에 PRD-001, PRD-002 같은 고유 ID를 부여하세요. 폴더명과 판매 플랫폼(Gumroad 등)의 상품명 끝에 이 ID를 함께 기록해 두면 검색 및 관리가 월등히 쉬워집니다.

2. 시맨틱 버저닝(Semantic Versioning) 규칙 적용

문서를 수정할 때 날짜(20260725) 대신 vX.Y.Z 형태의 버저닝 규칙을 사용하면, 고객에게 변경의 무게를 명확히 전달할 수 있습니다.

• v1.0.0 (Major): 대대적인 개정 (체계 변경, 전체 분량의 30% 이상 수정/추가)
• v1.1.0 (Minor): 내용 추가 및 개선 (새로운 챕터 추가, 최신 SDK/라이브러리 업데이트 반영)
• v1.1.1 (Patch): 단순 오류 수정 (오탈자, 잘못된 링크 수정, 표기 오류 정정)

파일명 부여 예시:

PRD-001_ESP32_QuickStart_v1.2.0_202607.pdf

(3 Build 폴더 안에는 항상 최신 버전만 유지하고, 구버전은 Archives 폴더로 이동)

3. Git 기반의 버전 관리 (개발자 스타일 버전 관리)

텍스트나 Markdown 기반으로 문서를 자주 작성하신다면, 코드 관리용 도구인 Git + GitHub(또는 GitLab)을 문서 관리에 도입하는 것이 가장 강력합니다.

[작성/수정] ──> [Git Commit (변경이력 기록)] ──> [PDF/전자책 빌드] ──> [판매 플랫폼 업로드]

• 장점:
  • 특정 시점으로의 완벽한 복구(Rollback)가 가능합니다.
  • 무엇이 수정되었는지 차이점(Diff)을 한눈에 볼 수 있습니다.
  • 파일명이 '진짜최종'으로 더러워지지 않고 main 단 하나로 유지됩니다.
• 추천 툴:
  • Obsidian / VS Code: Markdown 기반 문서 작성
  • GitKraken / Sourcetree: 복잡한 Git 명령어 없이 클릭만으로 버전 관리할 수 있는 GUI 툴

Word/HWP 문서를 주로 사용하신다면?

소스 파일이 binary 형태라면 Git보다는 OneDrive/Google Drive의 버전 기록(Version History) 기능이나 Dropbox를 결합하여 하드디스크와 실시간 동기화 및 백업을 유지하는 것이 현실적입니다.

4. 중앙 관리용 "문서 마스터 대장" (Notion 또는 Excel)

하드디스크 구조만으로는 "어느 플랫폼에 어떤 버전이 올라가 있는지" 추적하기 어렵습니다. 하나의 마스터 대장(Database)을 만들어 통합 관리하세요.

문서 ID	문서명	현재 버전	수정일	소스 위치 (하드디스크)	판매 플랫폼 (Gumroad 등)	비고 / 변경 로그
PRD-001	ESP32 IoT 가이드	v1.2.0	2026-07-20	D:\...\PRD-001_ESP32	[링크] (업로드완료)	ESP32-S3 내용 추가
PRD-002	회로설계 입문	v1.0.1	2026-07-25	D:\...\PRD-002_PCB	[링크] (검토중)	3페이지 오탈자 수정

Notion의 데이터베이스 기능을 활용하면, 관련 파일 경로, 업데이트 노트를 패치별로 나열하여 보기 쉽게 정리할 수 있습니다.

 

 

🅿️ Markdown 기반으로 문서를 작성하고 Git과 VS Code로 버전 관리 및 PDF를 자동 빌드하는 구체적인 세팅 방법을 알려주세요. 

 

Markdown 문서 작성부터 Git 버전 관리, 그리고 버튼 하나(또는 저장 시)로 깔끔한 PDF를 자동 변환하는 VS Code 중심의 워크플로우 세팅법을 정리해 드립니다.

이 환경을 구축해 두면, 하드디스크의 소스 파일은 깔끔한 Markdown(.md) 파일 하나로 유지하면서 출판용 PDF를 즉시 생성할 수 있습니다.

1. 필수 프로그램 및 VS Code 확장 프로그램 설치

기본 프로그램

• Git: git-scm.com에서 설치
• VS Code: code.visualstudio.com에서 설치

VS Code 핵심 확장 (Extensions)

VS Code 좌측 확장 탭(Ctrl+Shift+X)에서 다음 두 항목을 검색해 설치합니다.

1. Marp for VS Code (추천) 또는 Markdown PDF
   • Marp: 슬라이드 형태나 가로/세로 비율이 정돈된 기술 문서 및 전자책 출판에 가장 깔끔한 PDF 레이아웃을 제공합니다.
   • Markdown PDF: 일반적인 A4 문서 형태의 긴 글을 변환할 때 유용합니다.
2. Git Graph
   • 문서의 변경 이력(커밋)을 시각적인 그래프로 보여주어 버전 추적이 매우 편리해집니다.

2. 작업 공간 및 프로젝트 구조 세팅

VS Code에서 문서 프로젝트 전용 폴더를 열고 아래와 같이 파일 구조를 생성합니다.

Plaintext

 

my-doc-project/
├── .git/                 # Git 로컬 저장소
├── .gitignore            # Git 관리 제외 설정
├── assets/               # 이미지, 회로도 등 첨부 파일
│   └── architecture.png
├── builds/               # 자동 생성될 PDF 저장소
└── PRD-001_ESP32_Guide.md # 메인 작성 문서

.gitignore 파일 작성

빌드된 PDF나 임시 파일이 Git 저장소를 용량을 쓸데없이 차지하지 않도록, 프로젝트 루트에 .gitignore 파일을 만들고 아래 내용을 입력합니다.

Plaintext

 

# 빌드 결과물 제외 (소스인 .md만 Git으로 관리)
builds/
*.pdf
*.html

# OS 및 에디터 임시 파일
.DS_Store
.vscode/

3. Markdown 문서 작성 및 메타데이터 설정

Marp를 활용하면 문서 상단에 Front-matter(메타데이터)를 정의하여 PDF 스타일, 쪽 번호, 헤더/푸터를 고정할 수 있습니다.

PRD-001_ESP32_Guide.md 예시:

Markdown

 

---
marp: true
theme: default
paginate: true
header: "PRD-001: ESP32 시작 가이드 (v1.0.0)"
footer: "Copyright © CareLab. All rights reserved."
style: |
  section {
    font-family: 'Malgun Gothic', sans-serif;
    padding: 40px;
  }
  h1 { color: #0056b3; }
---

# ESP32 IoT 개발 입문 가이드

## 1. 개요
본 문서는 ESP32-S3 기반의 모듈 제어 및 펌웨어 작성 절차를 설명합니다.

![architecture](./assets/architecture.png)

---

## 2. 주요 스펙
* **MCU:** ESP32-S3 Dual-core
* **Wi-Fi / BT:** 2.4GHz Wi-Fi & Bluetooth 5 (LE)

4. PDF 자동 빌드 및 변환 방법

방법 A: VS Code UI로 1초 만에 내보내기 (Marp 사용 시)

1. .md 문서를 연 상태에서 우측 상단의 Marp 아이콘(작은 슬라이드 모양)을 클릭합니다.
2. Export Slide Deck... 선택 후 파일 형식을 PDF로 지정하여 builds/ 폴더에 저장합니다.

방법 B: 저장할 때마다 자동으로 PDF 변환 (Markdown PDF 사용 시)

VS Code 설정(Ctrl+,)에서 Markdown-pdf: On Save 옵션을 체크하면, .md 파일을 저장(Ctrl+S)할 때마다 같은 폴더에 PDF가 자동으로 생성됩니다.

5. Git을 활용한 버전 관리 워크플로우

문서 작업 시 커밋(Commit)과 태그(Tag)를 활용해 버전을 고정하는 표준 흐름입니다.

1.작업 공간 변경사항 확인:VS Code 소스 제어 탭.

좌측 **소스 제어 탭(Ctrl+Shift+G)**에서 변경되거나 추가된 .md 파일 및 이미지 파일들을 확인합니다.

2.커밋(Commit) 작성:변경 이력 저장.

상단 메시지 창에 변경 내용을 명확하게 적고 Commit 버튼을 누릅니다.

예시: docs: v1.1.0 - ESP32-S3 Pinout 설명 및 예제 코드 추가

3.버전 태그(Tag) 달기:터미널 활용.

주요 출판 버전(Major/Minor 업데이트)이 완성되면 VS Code 하단 터미널(`Ctrl+``)에서 버전을 태그로 고정합니다.

Bash

 

git tag -a v1.1.0 -m "Release Version 1.1.0"

💡 실무 팁:

GitHub나 GitLab 등 원격 저장소를 연동해 두면, 로컬 하드디스크가 고장 나더라도 모든 문서 소스와 과거 수정 내역이 안전하게 보존됩니다.

 

 

🅿️ 웹에서 데이터베이스를 사용해 관리하느 방법이 있을까요? 제가 관리하는 서버는 이미 있습니다. 웹에서 목록을 관리하는 방안을 제안하세요. 

 

이미 직접 관리하시는 서버가 있다면, 웹 화면에서 데이터베이스(DB)를 통해 문서 목록, 버전, 파일 경로, 판매 링크 등을 편리하게 관리하는 시스템을 구축하기 매우 좋은 환경입니다.

개발 공수와 유지보수 편의성에 따라 가장 효과적인 3가지 관리 방안을 제안해 드립니다.

1. 노코드/저코드 Admin 툴 활용 (가장 추천 ⚡)

기존 서버에 데이터베이스(MySQL, PostgreSQL 등)를 두고, 그 위에 오픈소스 Admin 패널을 올리는 방식입니다. 코딩을 거의 하지 않고도 완벽한 웹 관리 화면을 얻을 수 있습니다.

• 추천 솔루션: Directus 또는 NocoDB
• 작동 방식:
  1. 관리 중인 서버에 Docker 컨테이너 형태로 설치
  2. 서버 DB(MySQL/PostgreSQL)와 연결
  3. Excel/Notion 표 스타일의 웹 UI가 자동으로 생성됨
• 장점:
  • 개발 부담 제로에 가까우며 설치 후 바로 사용 가능
  • 사용자 권한 관리, 파일 업로드, 검색, 필터링 기능 기본 제공
  • REST API / GraphQL을 자동 생성해주므로 나중에 외부 서비스 연동도 용이

2. 웹 기반 오픈소스 문서/지식 관리 시스템 (Wiki형)

데이터베이스뿐만 아니라 웹 UI 상에서 직접 문서를 수정/작성하고 버전까지 관리하고 싶다면 문서 전용 CMS를 올리는 것이 좋습니다.

• 추천 솔루션: BookStack 또는 Wiki.js
• 작동 방식: 서버에 설치 후 웹 브라우저에서 '책 - 장(Chapter) - 페이지' 구조로 문서와 목록을 관리
• 장점:
  • 문서 본문 작성 + 목록 및 버전 관리를 웹 단 하나에서 처리
  • 이미지 첨부, PDF 내보내기, 개정 이력(Revision History) 자동 저장
  • Markdown 편집기 지원

3. 프레임워크 기반 자체 웹 관리자 구축 (커스텀 최적화)

기존 서버에 Node.js, Python(Django/FastAPI), PHP 등이 동작 중이라면, 커스텀 관리자 페이지를 최소한의 코드로 구현하는 방법입니다.

• 추천 기술 스택:
  • 백엔드: Python (Django Admin) 또는 Node.js (Express + Prisma)
  • DB: PostgreSQL / MySQL / SQLite
• 핵심 DB 테이블 구조 설계 예시:

SQL

 

CREATE TABLE documents (
    id VARCHAR(20) PRIMARY KEY,          -- 예: 'PRD-001'
    title VARCHAR(250) NOT NULL,          -- 문서명
    category VARCHAR(50),                 -- 카테고리 (IoT, Firmware 등)
    current_version VARCHAR(20),          -- 최신 버전 ('v1.2.0')
    file_path VARCHAR(500),               -- 서버/하드디스크 내 저장 경로
    sales_url VARCHAR(500),               -- Gumroad 등 판매 링크
    status VARCHAR(20) DEFAULT 'ACTIVE',  -- 상태 ('DRAFT', 'PUBLISHED', 'ARCHIVED')
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

💡 추천 선택 기준

요구사항	추천 방안
"개발 시간 없이 빨리 DB에 표 형태 웹 UI로 파일/버전 목록을 입력/관리하고 싶다"	Directus 또는 NocoDB
"서버 내에서 작성/수정부터 버전 관리, 목록 관리까지 웹으로 다 끝내고 싶다"	BookStack
"기존 서버의 기존 DB schema나 워크플로우에 딱 맞추어 개별 커스텀 기능을 넣고 싶다"	Django Admin 또는 자체 커스텀 웹페이지

가지고 계신 서버 환경(OS, Docker 사용 여부, 선호 언어 등)을 알려주시면 가장 빠르게 설치하고 구성할 수 있는 상세 세팅법을 안내해 드리겠습니다.

 

 

직장인 문서 목록을 관리하는 방법을 설명하는 이미지