🚀 Getting Started Guide

beginner's guide to using the Research Project Template

Quick Reference: Cheatsheet | Common Workflows | FAQ

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

Quick Start

Step 1: Get the Template

Click "Use this template" on GitHub
Name your repository (e.g., "my-research-project")

Clone your new repository

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

Step 2: Install Dependencies

macOS:

# 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 Python dependencies
pip install uv
uv sync

Ubuntu/Debian:

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

# Install Python dependencies
pip3 install uv
uv sync

Step 3: Generate Your First PDF

# Run the unified interactive menu and select Option 8 (Full Pipeline)
./run.sh

# Open the result (example project code_project)
open output/code_project/pdf/code_project_combined.pdf  # macOS
xdg-open output/code_project/pdf/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:

projects/code_project/manuscript/
├── preamble.md              # LaTeX styling (don't edit yet)
├── 01_abstract.md           # Research overview
├── 02_introduction.md       # Project introduction
├── 03_methodology.md        # Methods and approach
├── 04_experimental_results.md  # Results and findings
├── 05_discussion.md         # Analysis
├── 06_conclusion.md         # Summary
└── 99_references.md         # Bibliography

Edit the Abstract

Open the abstract file

vim projects/code_project/manuscript/01_abstract.md
# Or use your preferred text editor

You'll see:

# Abstract {#sec:abstract}

This template demonstrates...

Replace with your content:

# 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...

Save the file

Edit the Introduction

Open the introduction

vim projects/code_project/manuscript/02_introduction.md

Add your content:

# 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

Save the file

Generate Your PDF

Run pipeline

# Core pipeline (ten stages by default: clean through copy outputs)
uv run python scripts/execute_pipeline.py --project {name} --core-only

# Or use unified interactive menu
./run.sh

View the result

open output/code_project/pdf/code_project_combined.pdf  # After copy outputs: output/{name}/pdf/

What You Get:

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

Edit Multiple Sections

Continue editing other sections:

Methodology (03_methodology.md): Your research methods
Results (04_experimental_results.md): Your findings
Discussion (05_discussion.md): Analysis and interpretation
Conclusion (06_conclusion.md): Summary and future work

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:

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

Numbered Equations

For important equations you'll reference later:

\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

To refer to an equation elsewhere:

Using the quadratic formula \eqref{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:

# Methodology {#sec:methodology}

## Data Collection {#sec:data_collection}

Reference Sections

To refer to a section:

As described in Section \ref{sec:methodology}, we collected...

The data collection process (Section \ref{sec:data_collection}) involved...

Adding Figures

Even though you're not generating figures yet, you can reference existing ones:

\begin{figure}[h]
\centering
\includegraphics[width=0.8\textwidth]{../output/figures/example_figure.png}
\caption{Example visualization showing convergence behavior}
\label{fig:example}
\end{figure}

Figure \ref{fig:example} demonstrates the algorithm's performance.

Figure Anatomy:

[h] - Place here (h = here, t = top, b = bottom)
width=0.8\textwidth - 80% of text width
caption{} - Description below figure
label{} - Unique name for referencing

Example

Here's a methodology section with equations and references:

# 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 Equation \eqref{eq:update}, we use gradient descent with 
step size $\alpha_k$.

## Convergence Analysis

From equations \eqref{eq:objective} and \eqref{eq:update}, we can prove 
convergence under standard assumptions (see Section \ref{sec:results}).

Level 3: Basic Customization

Goal: Personalize your project

Time: 30-45 minutes

Customize Project Metadata

Method 1: Environment Variables

# 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/execute_pipeline.py --project {name} --core-only

Method 2: Create .env File

Copy template

cp infrastructure/config/.env.template .env

Edit .env
```
vim .env
```

Add your information

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

Source and build

source .env
uv run python scripts/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:

Open preamble

vim projects/code_project/manuscript/preamble.md

Find color definitions (around line 97-103):

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

Add your colors:

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

Use in hyperlinks (around line 54-60):

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

See code_project/manuscript/preamble.md for the LaTeX preamble configuration.

Add Bibliography

Edit references.bib

vim projects/code_project/manuscript/references.bib

Add entries:

@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}
}

Cite in manuscript:

Recent advances \cite{smith2020climate} demonstrate...

For review, see \cite{jones2019ai}.

Rebuild to see citations

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

Quick Tips

Writing Tips

Keep sections focused: One main idea per section
Use clear headings: Help readers navigate
Add labels consistently: {#sec:descriptive_name}
Reference liberally: Connect ideas across sections
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/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:

Check pandoc installed: pandoc --version
Check xelatex installed: xelatex --version

Clean and rebuild:

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

Missing Dependencies

Problem: ModuleNotFoundError: No module named 'matplotlib'

Solutions:

Ensure matplotlib is in core dependencies (not optional):

# root pyproject.toml
[project]
dependencies = ["matplotlib>=3.7"]  # Not in optional-dependencies

Run uv sync to install

Project Not Found

Problem: Project doesn't appear in menu

Solutions:

Ensure manuscript/config.yaml exists
Check project is in projects/ (not projects_archive/)

References Show ??

Problem: Cross-references display as ??

Solutions:

Check label exists: Search for {#sec:labelname}
Check spelling matches exactly

Rebuild (references need multiple passes):

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

Math Not Rendering

Problem: Equations display as plain text

Solutions:

Check equation environment syntax
Use \begin{equation} not $$
Check for unescaped special characters
Rebuild PDF

Can't Find File

Problem: Figure or reference not found

Solutions:

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

Success Checklist

After completing this guide, you should be able to:

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

Congratulations! You've mastered the basics. Ready for more? Check out Figures and Analysis.

Need help? Check the FAQ or Common Workflows

Quick Reference: Cheatsheet | Glossary

FilesExpand file tree

getting-started.md

Latest commit

History

getting-started.md

File metadata and controls

🚀 Getting Started Guide

📚 What You'll Learn

🎯 Prerequisites

📖 Table of Contents

Quick Start

Step 1: Get the Template

Step 2: Install Dependencies

Step 3: Generate Your First PDF

Level 1: Write Your First Document

Understanding the Manuscript Structure

Edit the Abstract

Edit the Introduction

Generate Your PDF

Edit Multiple Sections

Level 2: Add Equations and References

Adding Mathematical Equations

Simple Inline Math

Numbered Equations

Referencing Equations

Common Math Symbols

Cross-Referencing Sections

Add Section Labels

Reference Sections

Adding Figures

Example

Level 3: Basic Customization

Customize Project Metadata

Method 1: Environment Variables

Method 2: Create .env File

Customize LaTeX Styling

Add Bibliography

Quick Tips

Writing Tips

Common Mistakes

Keyboard Shortcuts

Troubleshooting

Build Fails

Missing Dependencies

Project Not Found

References Show ??

Math Not Rendering

Can't Find File

What to Read Next

If you're ready to

Related Documentation

Success Checklist