dissertation-template/README.md

# Dissertation LaTeX Template

A clean, modular LaTeX template for PhD dissertations. Designed for compatibility with both **Overleaf** (web-based, no installation) and **local toolchains** like VimTeX.

---

## Quick Start

### Overleaf (Recommended for Beginners)

1. Download this repository as a ZIP file.
2. In Overleaf, click **New Project → Upload Project** and select the ZIP.
3. Open `definitions.tex` and fill in your metadata (name, title, committee, etc.).
4. Write your chapters in `chapter/<name>/main.tex` files.
5. Add bibliography entries to `bibliography.bib`.
6. Click **Recompile** to build.

> **Note:** Overleaf automatically detects `.latexmkrc` and uses the correct build settings. No manual compiler configuration needed.

### Local Build (VimTeX / CLI)

**Prerequisites:** A working TeX distribution (TeX Live, MiKTeX, or MacTeX) with `latexmk` and `biber` installed.

**Build:**
```bash
latexmk main.tex
```

**Clean auxiliary files:**
```bash
latexmk -c main.tex
```

**Clean everything (including PDF):**
```bash
latexmk -C main.tex
```

**Continuous preview (auto-rebuild on save):**
```bash
latexmk -pvc main.tex
```

**Or use the Makefile:**
```bash
make          # Build
make clean    # Clean aux files
make distclean # Clean everything
make watch    # Continuous preview
```

**VimTeX users:** The included `.latexmkrc` is automatically picked up by VimTeX. Just open `main.tex` in Neovim/Vim and use your usual VimTeX mappings (e.g., `<localleader>ll` to compile, `<localleader>lv` to view).

---

## Project Structure

```
.
├── main.tex                      # Root document (do not edit structure lightly)
├── definitions.tex               # Your metadata: name, title, committee, etc.
├── definitions-extra.tex         # Extra preamble: custom commands, theorem styles
├── bibliography.bib              # BibLaTeX bibliography database
├── .latexmkrc                    # Build configuration (Overleaf + local)
├── Makefile                      # CLI shortcuts
├── README.md                     # This file
│
├── dissertation-style/           # Internal style files (rarely need editing)
│   ├── preamble.tex              # Package imports and setup
│   ├── front-matter.tex          # Title page, abstract, TOC, etc.
│   └── back-matter.tex           # Appendix setup
│
├── front-matter/                 # Content for roman-numeraled pages
│   ├── abstract.tex              # Dissertation abstract
│   ├── dedication.tex            # Optional dedication page
│   └── acknowledgements.tex      # Optional acknowledgements
│
└── chapter/                      # Your chapters
    ├── introduction/
    │   └── main.tex              # Introduction chapter
    └── conclusion/
        └── main.tex              # Conclusion chapter
    # Add more: chapter/<name>/main.tex, then \input in main.tex
```

---

## Customization Guide

### 1. Set Your Metadata

Edit `definitions.tex`:

```latex
\def\dissertationtitle{Your Actual Title}
\def\fullname{Your Full Name}
\def\defenseyear{2027}
\def\defensemonth{May}
\def\defenseday{15}
\def\advisor{Dr. Advisor Name}
```

Also update:
- `\university`, `\department`, `\degree` (defaults to Duke Math PhD)
- Committee members in `\committeelist`

### 2. Enable/Disable Optional Pages

In `definitions.tex`, toggle these flags:

```latex
\dedicationtrue        % Dedication page
\tablestrue            % List of Tables
\figurestrue           % List of Figures
\symbolstrue           % List of Symbols (requires makeglossaries)
\acknowledgementstrue  % Acknowledgements
\appendixtrue          % Appendices
```

Comment out or set `\...false` to disable.

### 3. Add a New Chapter

1. Create the directory: `chapter/my_chapter/`
2. Create `chapter/my_chapter/main.tex`:
   ```latex
   \chapter{My Chapter Title}
   \section{First Section}
   Your content here.
   ```
3. Add to `main.tex`:
   ```latex
   \input{chapter/my_chapter/main.tex}
   ```

### 4. Add Bibliography Entries

Edit `bibliography.bib`:

```bibtex
@article{smith2024,
  author  = {Smith, Alice and Jones, Bob},
  title   = {A Great Paper},
  journal = {Journal of Examples},
  year    = {2024},
  volume  = {42},
  pages   = {1--20}
}
```

Cite in your text: `\cite{smith2024}`.

### 5. Define Symbols (Optional)

If `\symbolstrue` is enabled, add symbols in `definitions.tex`:

```latex
\glsxtrnewsymbol[description={the special linear group}]{SL2}{\ensuremath{\mathrm{SL}(2, \mathbb{R})}}
```

They will appear in the List of Symbols.

---

## Troubleshooting

| Problem | Solution |
|---|---|
| "Missing bibliography" error | Ensure `bibliography.bib` exists and has at least one entry. Run `latexmk` twice. |
| "Missing glossary" error | The `.latexmkrc` runs `makeglossaries` automatically. If building manually, run `makeglossaries main` between pdflatex passes. |
| Overleaf won't compile | Check that `definitions.tex` has no unfilled `%% FILL IN %%` comments left in active macro definitions. |
| VimTeX not detecting `.latexmkrc` | Ensure your VimTeX config does not override `g:vimtex_compiler_latexmk`. The defaults work. |

---

## License

MIT License — see [LICENSE](LICENSE) for details.

You are free to use, modify, and distribute this template for personal or departmental use.