SuperAPI AI Directory

latex-project-manager

General & other

View repository

Updated 10-15 19:47

About this skill

LaTeX Project Manager

This is a skill for separating a LaTeX project into a folder structure by section and managing it with Git.

When to Use

  • single .tex when 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 between main.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 .bib manage 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/@inproceedings convert 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:

  1. Environment variable $GITHUB_TOKEN or $OVERLEAF_TOKEN
  2. 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 review
  • iterative-academic-writer — academic document quality improvement loop