path: root/README

# Academic Marp (acarp) Theme

![Academic Marp Theme](acarp.png)

A minimal, grid-based theme for Marp presentations designed for academic content.

## Features

- **Grid-only layouts** - CSS Grid for all presentation layouts
- **Two aspect ratios** - 16:9 (standard) and 4:3 (beamer)
- **Academic focus** - Optimized for equations, code, and technical content
- **Explicit contracts** - Clear, maintainable CSS structure
- **No utility classes** - Focus on content, not class names

## Quick Start

### Install
```bash
npm install
```

### Build Examples
```bash
# Using just (recommended)
just demo  # Build both demo presentations

# Using npx directly
npx marp --config .marprc.json --html demo-standard.md
npx marp --config .marprc.json --html demo-beamer.md

# Export to PDF
npx marp --config .marprc.json --pdf demo-standard.md
```

## Available Layouts

### `title` - Cover Slide
```markdown
---
<!-- _class: title -->
# Presentation Title
## Subtitle or Author
```

### `layout-2col` - Two Columns
```markdown
---
<!-- _class: layout-2col -->
### Slide Title

<div class="left-column">
Text content
</div>

<div class="right-column">
![](figs/image.png)
</div>
```

### Default - Single Column
```markdown
---
### Slide Title

Your content here
```

## Common Patterns

### Code + Output
```markdown
---
<!-- _class: layout-2col -->
### Python Example

<div class="left-column">
```python
def hello(name):
    return f"Hello {name}"
```
</div>

<div class="right-column">
```
>>> hello("World")
'Hello World'
```
</div>
```

## Themes

### Standard (16:9)
- Dimensions: 1280x720px
- Use default theme
- For modern widescreen presentations

### Beamer (4:3)
- Dimensions: 1280x960px
- Use filename with "beamer": `talk-beamer.md`
- For classic LaTeX Beamer-style presentations

## Customization

### Theme Variables
Edit `acarp.css` to modify colors, fonts, spacing:

```css
:root {
  --slide-width: 1280px;
  --slide-height: 720px;
  --padding: 70px;
  --color-background: #fdfcff;
  --color-foreground: #202228;
  --color-highlight: #009dd5;
}
```

For beamer-specific overrides, edit `acarp-beamer.css`.

### Font Size Customization
You can override font sizes in your markdown frontmatter:

```yaml
---
marp: true
theme: acarp
style: |
  section {
    font-size: 32px !important;  /* Larger base font */
  }
  h1 { font-size: 2.5em !important; }  /* Larger headings */
---
```

Common font sizes:
- Standard theme: 28px (default)
- Beamer theme: 37px (default)
- Large print: 32-36px
- Compact: 24-26px

### Logo Placement
Add a logo to the top-right corner using CSS variables in your frontmatter:

```yaml
---
marp: true
theme: acarp
style: |
  :root {
    --logo-image: url('logo.png');
    --logo-width: 120px;
    --logo-height: 50px;
    --logo-top: 20px;
    --logo-right: 20px;
    --logo-opacity: 0.8;
  }
---
```

**Logo Variables:**
- `--logo-image`: Path to your logo file
- `--logo-width`: Logo width (default: 100px)
- `--logo-height`: Logo height (default: 40px)
- `--logo-top`: Distance from top (default: 20px)
- `--logo-right`: Distance from right (default: 20px)
- `--logo-opacity`: Transparency (0-1, default: 0.7)

The logo appears on all slides except the title slide.

## All Commands

```bash
just build <file>      # Build HTML
just watch <file>      # Watch and auto-rebuild
just pdf <file>        # Export to PDF
just new <name>        # Create new presentation
just clean             # Remove output files
just demo              # Build demo presentations
just help              # Show all commands
```

## Design Philosophy

The theme is built on a simple principle: use CSS Grid exclusively for layout. This means:

- **Grid only** - No flexbox for layouts (flexbox is for UI components)
- **Explicit contracts** - Grid areas and templates are clearly defined
- **Minimal abstraction** - No utility classes, no hidden behaviors
- **Maintainable** - One base theme, one beamer override

## Directory Structure

```
acarp-marp-theme/
├── figs/              # Images directory
├── acarp.css          # Base theme (all layouts)
├── acarp-beamer.css   # Beamer overrides (4:3 only)
├── .marprc.json       # Marp configuration
├── template.md        # Example presentation
├── demo-standard.md   # Standard 16:9 example
├── demo-beamer.md     # Beamer 4:3 example
├── package.json       # Dependencies
├── justfile           # Build commands
└── README.md          # This file
```

## Notes

- Images: `![](figs/imagename.png)`
- Math: `$$...$$` for display, `$...$` for inline
- Code blocks: Use ` ``` ` (automatic syntax highlighting)
- PDF/PPTX export requires Chrome or Chromium