# 🚀 Getting Started Guide

> **beginner's guide** to using the Research Project Template

**Quick Reference:** [Cheatsheet](../reference/quick-start-cheatsheet.md) | [Common Workflows](../reference/common-workflows.md) | [FAQ](../reference/faq.md)

This guide covers **Levels 1-3** of the Research Project Template. for users who just want to write documents without programming.

## 📚 What You'll Learn

By the end of this guide, you'll be able to:

- ✅ Set up the template on your computer
- ✅ Write and format professional documents
- ✅ Add equations and cross-references
- ✅ Generate publication-ready PDFs
- ✅ Customize project metadata

**Estimated Time:** 2-3 hours

## 🎯 Prerequisites

- Basic computer skills
- Text editor (any will work)
- No programming knowledge required

## 📖 Table of Contents

- [Quick Start](#quick-start)
- [Level 1: Write Your First Document](#level-1-write-your-first-document)
- [Level 2: Add Equations and References](#level-2-add-equations-and-references)
- [Level 3: Basic Customization](#level-3-basic-customization)
- [What to Read Next](#what-to-read-next)

---

## Quick Start

### Step 1: Get the Template

1. **Click "Use this template"** on [GitHub](https://github.com/docxology/template)
2. **Name your repository** (e.g., "my-research-project")
3. **Clone your new repository**

   ```bash
   git clone https://github.com/YOUR_USERNAME/your-repo-name.git
   cd your-repo-name
   ```

### Step 2: Install Dependencies

**macOS:**

```bash
# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install system dependencies
brew install pandoc
brew install --cask mactex

# Install uv and Python dependencies
brew install uv
uv sync
```

**Ubuntu/Debian:**

```bash
# Install system dependencies
sudo apt-get update
sudo apt-get install -y pandoc texlive-xetex texlive-fonts-recommended fonts-dejavu

# Install uv and Python dependencies
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync
```

### Step 3: Generate Your First PDF

```bash
# Run the unified interactive menu and select Option 8 (Core Pipeline) for your
# first run — it needs no LLM or network, matching START_HERE.md's quick path.
# Option 9 (Full Pipeline) adds the two Ollama-backed LLM stages once you have
# a local model set up. See `docs/RUN_GUIDE.md` for the full menu map.
./run.sh

# Open the result (example project template_code_project)
open output/templates/template_code_project/pdf/template_code_project_combined.pdf  # macOS
xdg-open output/templates/template_code_project/pdf/template_code_project_combined.pdf  # Linux
```

**🎉 Success!** You should see a professional PDF document.

---

## Level 1: Write Your First Document

**Goal**: Create professional documents without programming

**Time**: 30-45 minutes

### Understanding the Manuscript Structure

The template provides pre-structured manuscript files in the `manuscript/` directory:

```mermaid
flowchart TB
    M[projects/templates/template_code_project/manuscript/]
    M --> PRE[preamble.md<br/>LaTeX styling]
    M --> ABS[00_abstract.md<br/>Research overview]
    M --> INTRO[01_introduction.md]
    M --> METH[02_methodology.md]
    M --> RES[03_results.md]
    M --> CONC[04_conclusion.md]
    M --> EXP[05_experimental_setup.md]
    M --> REP[06_reproducibility.md]
    M --> SCOPE[07_scope_and_related_work.md]
    M --> BIB[references.bib<br/>Bibliography]

    classDef d fill:#0f172a,stroke:#0f172a,color:#fff
    classDef f fill:#0f766e,stroke:#0f172a,color:#fff
    class M d
    class PRE,ABS,INTRO,METH,RES,CONC,EXP,REP,SCOPE,BIB f
```

### Edit the Abstract

1. **Open the abstract file**

   ```bash
   vim projects/templates/template_code_project/manuscript/00_abstract.md
   # Or use your preferred text editor
   ```

2. **You'll see**:

   ```markdown
   # Abstract {#sec:abstract}

   This template demonstrates...
   ```

3. **Replace with your content**:

   ```markdown
   # Abstract {#sec:abstract}

   This research investigates the impact of machine learning on climate
   prediction accuracy. We developed a novel ensemble method combining
   neural networks with traditional models...
   ```

4. **Save the file**

### Edit the Introduction

1. **Open the introduction**

   ```bash
   vim projects/templates/template_code_project/manuscript/01_introduction.md
   ```

2. **Add your content**:

   ```markdown
   # Introduction {#sec:introduction}

   ## Background

   Climate change poses significant challenges...

   ## Motivation

   Current prediction methods have limitations...

   ## Objectives

   This research aims to:
   1. Develop improved prediction models
   2. Validate accuracy across multiple datasets
   3. Provide actionable recommendations
   ```

3. **Save the file**

### Generate Your PDF

1. **Run pipeline**

   ```bash
   # Core pipeline (eight stages: clean through copy outputs; LLM stages excluded)
   uv run python scripts/runner/execute_pipeline.py --project {name} --core-only

   # Or use unified interactive menu
   ./run.sh
   ```

2. **View the result**

   ```bash
   open output/templates/template_code_project/pdf/template_code_project_combined.pdf  # After copy outputs: output/templates/{name}/pdf/
   ```

**What You Get**:

- ✅ Professional formatting
- ✅ Automatic section numbering
- ✅ Table of contents
- ✅ Proper academic style

### Edit Multiple Sections

Continue editing other sections:

- **Methodology** (`02_methodology.md`): Your research methods
- **Results** (`03_results.md`): Your findings
- **Conclusion** (`04_conclusion.md`): Summary and future work
- **Experimental Setup** (`05_experimental_setup.md`): Setup and configuration
- **Reproducibility** (`06_reproducibility.md`): Reproducibility notes

**After each major change**, regenerate the PDF to see your progress.

---

## Level 2: Add Equations and References

**Goal**: Add mathematical equations and cross-references

**Time**: 45-60 minutes

### Adding Mathematical Equations

#### Simple Inline Math

For math within text, use dollar signs:

```markdown
The quadratic formula $x = \frac{-b \pm \sqrt{b^2-4ac}}{2a}$ solves...
```

#### Numbered Equations

For important equations you'll reference later:

```markdown
\begin{equation}\label{eq:quadratic}
x = \frac{-b \pm \sqrt{b^2-4ac}}{2a}
\end{equation}
```

**Key Parts**:

- `\begin{equation}` - Start equation
- `\label{eq:quadratic}` - Unique name for referencing
- `\end{equation}` - End equation

#### Referencing Equations

**Use Pandoc bracket-cite syntax to refer to an equation, not raw `\eqref{}`** — `[@eq:label]` is the canonical, portable form (see [Manuscript Semantics](manuscript-semantics.md) for the full rule set):

```markdown
Using the quadratic formula [@eq:quadratic], we can solve...
```

### Common Math Symbols

| Symbol | LaTeX | Example |
|--------|-------|---------|
| Fraction | `\frac{a}{b}` | $\frac{a}{b}$ |
| Square root | `\sqrt{x}` | $\sqrt{x}$ |
| Superscript | `x^2` | $x^2$ |
| Subscript | `x_1` | $x_1$ |
| Sum | `\sum_{i=1}^{n}` | $\sum_{i=1}^{n}$ |
| Integral | `\int_0^1` | $\int_0^1$ |
| Greek letters | `\alpha, \beta` | $\alpha, \beta$ |

### Cross-Referencing Sections

#### Add Section Labels

When creating a section heading, add a label:

```markdown
# Methodology {#sec:methodology}

## Data Collection {#sec:data_collection}
```

#### Reference Sections

**Use `[@sec:label]`, not raw `\ref{}` or a Markdown filename link** — this is the one syntax that stays stable across PDF, HTML, and EPUB output:

```markdown
As described in [@sec:methodology], we collected...

The data collection process ([@sec:data_collection]) involved...
```

### Adding Figures

Even though you're not generating figures yet, you can reference existing ones. **Use Pandoc's image syntax with a `{#fig:label}` attribute, not a raw LaTeX `figure` environment** — this is what every exemplar manuscript in this repo actually uses, and it renders correctly in PDF, HTML, and EPUB alike:

```markdown
![Example visualization showing convergence behavior.](../output/figures/convergence_plot.png){#fig:example width=80%}

[@fig:example] demonstrates the algorithm's performance.
```

**Figure Anatomy**:

- `![caption](path)` - Pandoc image syntax; the caption appears below the figure in the PDF and as alt text in HTML/EPUB
- `width=80%` - 80% of text width
- `{#fig:example}` - Unique label for cross-referencing
- `[@fig:example]` - Cross-reference (parenthetical); use bare `@fig:example` for a narrative reference ("Figure 3 shows…")

### Example

Here's a methodology section with equations and references:

```markdown
# Methodology {#sec:methodology}

## Mathematical Framework

Our approach is based on the optimization problem:

\begin{equation}\label{eq:objective}
\min_{x \in \mathbb{R}^n} f(x) = \sum_{i=1}^{n} w_i \phi_i(x)
\end{equation}

where $w_i$ are weights and $\phi_i$ are basis functions.

## Algorithm

The iterative update follows:

\begin{equation}\label{eq:update}
x_{k+1} = x_k - \alpha_k \nabla f(x_k)
\end{equation}

As shown in [@eq:update], we use gradient descent with
step size $\alpha_k$.

## Convergence Analysis

From [@eq:objective] and [@eq:update], we can prove
convergence under standard assumptions (see [@sec:results]).
```

---

## Level 3: Basic Customization

**Goal**: Personalize your project

**Time**: 30-45 minutes

### Customize Project Metadata

#### Method 1: Environment Variables

```bash
# Set your information
export AUTHOR_NAME="Dr. Jane Smith"
export AUTHOR_EMAIL="jane.smith@university.edu"
export AUTHOR_ORCID="0000-0001-2345-6789"
export PROJECT_TITLE="Impact of Machine Learning on Climate Prediction"

# Optional: Add DOI if published
export DOI="10.5281/zenodo.12345678"

# Generate with your metadata
uv run python scripts/runner/execute_pipeline.py --project {name} --core-only
```

#### Method 2: Create .env File

1. **Copy template**

   ```bash
   cp infrastructure/config/.env.template .env
   ```

2. **Edit .env**

   ```bash
   vim .env
   ```

3. **Add your information**

   ```bash
   AUTHOR_NAME="Dr. Jane Smith"
   AUTHOR_EMAIL="jane.smith@university.edu"
   AUTHOR_ORCID="0000-0001-2345-6789"
   PROJECT_TITLE="Impact of Machine Learning on Climate Prediction"
   DOI=""  # Leave empty if not published yet
   ```

4. **Source and build**

   ```bash
   source .env
   uv run python scripts/runner/execute_pipeline.py --project {name} --core-only
   ```

**What Gets Updated**:

- ✅ PDF title page
- ✅ PDF metadata
- ✅ Author information
- ✅ Document properties

### Customize LaTeX Styling

**Note**: This is optional and more advanced. Skip if you're satisfied with defaults.

The template uses `manuscript/preamble.md` for styling. You can modify:

- **Colors**: Change link colors, heading colors
- **Fonts**: Modify font families and sizes
- **Spacing**: Adjust line spacing and margins
- **Headers/Footers**: Customize page headers

**Basic color customization**:

1. **Open preamble**

   ```bash
   vim projects/templates/template_code_project/manuscript/preamble.md
   ```

2. **Add `\definecolor` declarations** near the top of the preamble (the shipped file keeps its color setup above the `\hypersetup` block):

   ```latex
   \definecolor{codebg}{RGB}{248, 248, 248}
   \definecolor{codeborder}{RGB}{200, 200, 200}
   ```

3. **Add your colors**:

   ```latex
   \definecolor{myblue}{RGB}{0, 114, 178}
   \definecolor{mygreen}{RGB}{0, 158, 115}
   ```

4. **Use in hyperlinks** (in the `\hypersetup` block):

   ```latex
   \hypersetup{
       colorlinks=true,
       linkcolor=myblue,
       citecolor=mygreen,
       ...
   }
   ```

**See [template_code_project/manuscript/preamble.md](../../projects/templates/template_code_project/manuscript/preamble.md) for the LaTeX preamble configuration.**

### Add Bibliography

1. **Edit references.bib**

   ```bash
   vim projects/templates/template_code_project/manuscript/references.bib
   ```

2. **Add entries**:

   ```bibtex
   @article{smith2020climate,
     title={Machine Learning for Climate Prediction},
     author={Smith, Jane and Doe, John},
     journal={Nature Climate Change},
     volume={10},
     pages={123--130},
     year={2020}
   }

   @book{jones2019ai,
     title={Artificial Intelligence in Environmental Science},
     author={Jones, Alice},
     publisher={Academic Press},
     year={2019}
   }
   ```

3. **Cite in manuscript** (Pandoc bracket-cite syntax — never raw `\cite{}`, which breaks HTML/EPUB rendering; see [Manuscript Semantics](manuscript-semantics.md)):

   ```markdown
   Recent advances [@smith2020climate] demonstrate...

   For review, see [@jones2019ai].
   ```

4. **Rebuild to see citations**

   ```bash
   uv run python scripts/runner/execute_pipeline.py --project {name} --core-only
   ```

---

## Quick Tips

### Writing Tips

1. **Keep sections focused**: One main idea per section
2. **Use clear headings**: Help readers navigate
3. **Add labels consistently**: `{#sec:descriptive_name}`
4. **Reference liberally**: Connect ideas across sections
5. **Preview frequently**: Regenerate PDF to see changes

### Common Mistakes

| Mistake | Solution |
|---------|----------|
| **Forgot section label** | Add `{#sec:name}` after heading |
| **Reference shows ??** | Check label spelling matches |
| **Equation not numbered** | Use `\begin{equation}...\end{equation}` |
| **Figure not found** | Check path is `../output/figures/` |
| **PDF won't build** | Run `uv run python scripts/runner/execute_pipeline.py --project {name} --core-only` (includes cleanup) |

### Keyboard Shortcuts

**Most text editors**:

- Save: `Ctrl+S` (Linux/Windows) or `Cmd+S` (macOS)
- Find: `Ctrl+F` or `Cmd+F`
- Replace: `Ctrl+H` or `Cmd+Option+F`

**Vim users**:

- Save and quit: `:wq`
- Quit without saving: `:q!`
- Search: `/searchterm`

---

## Troubleshooting

### Build Fails

**Problem**: PDF generation fails

**Solutions**:

1. Check pandoc installed: `pandoc --version`
2. Check xelatex installed: `xelatex --version`
3. Clean and rebuild:

   ```bash
   uv run python scripts/runner/execute_pipeline.py --project {name} --core-only
   ```

### Missing Dependencies

**Problem**: `ModuleNotFoundError: No module named 'matplotlib'`

**Solutions**:

1. Ensure matplotlib is in core dependencies (not optional):
   ```toml
   # root pyproject.toml
   [project]
   dependencies = ["matplotlib>=3.7"]  # Not in optional-dependencies
   ```
2. Run `uv sync` to install

### Project Not Found

**Problem**: Project doesn't appear in menu

**Solutions**:

1. Ensure `manuscript/config.yaml` exists
2. Check project is in `projects/` (not `projects/archive/`)

### References Show ??

**Problem**: Cross-references display as `??`

**Solutions**:

1. Check label exists: Search for `{#sec:labelname}`
2. Check spelling matches exactly
3. Rebuild (references need multiple passes):

   ```bash
   uv run python scripts/runner/execute_pipeline.py --project {name} --core-only
   ```

### Math Not Rendering

**Problem**: Equations display as plain text

**Solutions**:

1. Check equation environment syntax
2. Use `\begin{equation}` not `$$`
3. Check for unescaped special characters
4. Rebuild PDF

### Can't Find File

**Problem**: Figure or reference not found

**Solutions**:

1. Check relative path: `../output/figures/name.png`
2. Verify file exists: `ls projects/{name}/output/figures/`
3. Run pipeline (includes script execution): `uv run python scripts/runner/execute_pipeline.py --project {name} --core-only`

---

## What to Read Next

### If you're ready to

**Add your own figures and data**
→ Read **[Figures and Analysis Guide](figures-and-analysis.md)** (Levels 4-6)

**Learn test-driven development**
→ Read **[Testing and Reproducibility Guide](testing-and-reproducibility.md)** (Levels 7-9)

**Understand the system architecture**
→ Read **[Architecture Guide](../core/architecture.md)**

**See real-world examples**
→ Read **[Examples Showcase](../usage/examples-showcase.md)**

**Find answers to common questions**
→ Read **[FAQ](../reference/faq.md)**

### Related Documentation

- **[Quick Start Cheatsheet](../reference/quick-start-cheatsheet.md)** - One-page reference
- **[Common Workflows](../reference/common-workflows.md)** - Step-by-step recipes
- **[Glossary](../reference/glossary.md)** - Terms and definitions
- **[Markdown Template Guide](../usage/markdown-template-guide.md)** - formatting reference
- **[Documentation Index](../documentation-index.md)** - All documentation

---

## Success Checklist

After completing this guide, you should be able to:

- [x] Install the template and dependencies
- [x] Edit manuscript sections
- [x] Add mathematical equations with labels
- [x] Create cross-references between sections
- [x] Generate professional PDFs
- [x] Customize project metadata
- [x] Add bibliography entries

**Congratulations!** You've mastered the basics. Ready for more? Check out **[Figures and Analysis](../guides/figures-and-analysis.md)**.

---

**Need help?** Check the **[FAQ](../reference/faq.md)** or **[Common Workflows](../reference/common-workflows.md)**

**Quick Reference**: [Cheatsheet](../reference/quick-start-cheatsheet.md) | [Glossary](../reference/glossary.md)