This is a skill for separating a LaTeX project into a folder structure by section and managing it with Git.
When to Use
- single
.texwhen you want to separate a file by section - when managing multiple LaTeX projects in a single repo using a switch method
- when pushing a LaTeX project to GitHub or Overleaf
- existing inline
\begin{thebibliography}를 BibTeX.bibwhen converting to
Command 1: structure
Usage
/latex-project-manager structure <tex_file> <output_dir> [project_name]
What It Does
single .tex Analyze the file and separate it into the structure below:
output_dir/
├── main.tex # 공통 preamble + 프로젝트 선택 스위치
├── <project_name>/
│ ├── content.tex # \input 오케스트레이터
│ ├── refs.bib # BibTeX 참고문헌
│ ├── figures/ # 이미지 저장 폴더
│ │ └── .gitkeep
│ └── sections/
│ ├── 00_frontmatter.tex # \title, \author, \maketitle, \abstract
│ ├── 01_<section_name>.tex # 각 \section별 파일
│ ├── ...
│ └── NN_bibliography.tex # \bibliography{project/refs}
└── .gitignore
Workflow
Phase 1: 분석
├── .tex 파일 읽기
├── preamble 추출 (documentclass ~ \begin{document})
├── \section 경계 식별
├── bibliography 방식 확인 (inline vs bibtex)
└── 패키지 목록 수집
Phase 2: 분리
├── main.tex 생성 (preamble + \professor 스위치)
├── content.tex 생성 (\input 목록)
├── 섹션별 .tex 파일 생성
├── refs.bib 생성 (inline bib → BibTeX 변환)
└── figures/ 디렉토리 생성
Phase 3: 검증
├── pdflatex 컴파일 (에러 0 확인)
├── bibtex 실행 + 재컴파일 (3-pass)
├── 원본 대비 페이지 수 일치 확인
├── citation 경고 0건 확인
└── 컨텐츠 유실 없음 확인 (diff)
Phase 4: Critique Loop
├── Round 1: 에러/경고 확인 → 수정
├── Round 2: 재검증 → 이슈 없으면 통과
└── 2회 연속 이슈 없을 때까지 반복
Rules
Preamble Handling
\documentclass~\begin{document}extract all content betweenmain.texto- when there are multiple projects, the package's unionuse
\graphicspath{{\professor/figures/}}set the image path per project with
Section Splitting
\section{...}separate by unit (subsections are included in the corresponding section file)- Filename:
NN_<section_name>.tex(number + snake_case) \title,\author,\date,\maketitle,\begin{abstract}~\end{abstract}→00_frontmatter.tex\section*{Acknowledgments}+ bibliography → last number_bibliography.tex
Bibliography (CRITICAL)
- must be BibTeX
.bibmanage as a file — inline\begin{thebibliography}prohibited refs.bibcreate at the project folder root\bibliographystyle{plainnat}+\bibliography{<project>/refs}use- inline
\bibitemif present, automatically@article/@inproceedingsconvert to entry - convert all text references to
\citep{}or\citet{}convert to — find plain text references like "(Author et al., Year)" and\citep{key}replace with - 3-pass compilation:
pdflatex → bibtex → pdflatex → pdflatex
Multi-Project Switch
% main.tex
\newcommand{\professor}{goodman} % Change to: goodman | andreas | lake
% ... shared preamble ...
\begin{document}
\input{\professor/content}
\end{document}
Content Preservation
- do not change the original content by even a single character (structure changes only)
- However, fix if there is a LaTeX error (e.g., pgfplots xticklabel
\\issue)
Command 2: push
Usage
/latex-project-manager push <project_dir> [remote_url]
Token Authentication
Priority:
- Environment variable
$GITHUB_TOKENor$OVERLEAF_TOKEN - ask the user for direct input
Git URL Formats
| service | URL format |
|---|---|
| GitHub | https://<user>:<token>@github.com/<user>/<repo>.git |
| Overleaf | https://git:<token>@git.overleaf.com/<project_id> |
Workflow
Phase 1: 초기화
├── git init (없는 경우)
├── .gitignore 생성/확인
├── remote 설정
└── user.name / user.email 설정
Phase 2: 커밋
├── git add (tex, bib, gitkeep, gitignore만)
├── 커밋 메시지 자동 생성
└── git commit
Phase 3: Push
├── git push (또는 force push for 초기 설정)
└── 결과 확인
Phase 4: Critique
├── git ls-files로 tracked 파일 확인
├── 민감 정보 (토큰 등) 커밋에 포함되지 않았는지 확인
└── remote 연결 상태 확인
.gitignore Template
*.aux
*.log
*.out
*.toc
*.bbl
*.blg
*.synctex.gz
*.fls
*.fdb_latexmk
*.pdf
.DS_Store
Common Issues & Fixes
| problem | cause | solution |
|---|---|---|
pgfplots xticklabel \\ error |
in LR mode, \\ cannot be used |
{Label Text} change to the form, add align=center add |
| Overfull hbox (table) | lcccc column is too wide |
Xcccc (tabularx) or abbreviate the header |
| Citation undefined | \cite reference as text without |
\citep{key} or \citet{key}convert to |
| Missing BibTeX entry | .bibno key in |
refs.bibadd entry to |
| Overleaf git 403 | free plan | Premium plan required, or use GitHub |
\legendin $\to$ error |
pgfplots legend's math mode limitation | \textrightarrow{} use |
Related Skills
academic-latex-pipeline— MD→LaTeX conversion, Korean font, Format reviewiterative-academic-writer— academic document quality improvement loop