poisson-template-astro/README.md

# Poisson Blog Template

![Poisson Blog Template](./public/cover.png)

An Astro-based academic blog template designed for the PHC (Dipartimento di Matematica) at University of Pisa. This template provides a clean, mathematical content-friendly platform for sharing academic posts, notes, and research materials.

## Features

- ✨ Built with [Astro](https://astro.build/) for fast, static site generation

- 📝 Support for Markdown and MDX content with mathematical expressions

- 🎨 Multiple customizable themes

- 🏷️ Tag-based post organization

- 📚 Dedicated sections for posts and notes

- 🔍 SEO-friendly structure

- 📱 Responsive design

## Available Themes

The template includes several pre-built themes located in `src/themes/`:

- **base.css** - Clean, minimal base theme

- **colorful.css** - Vibrant, colorful theme

- **modern.css** - Contemporary design with modern styling

- **mono.css** - Monochromatic, minimalist theme

- **sober.css** - Professional, academic-focused theme

To change themes, modify the CSS import in `src/layouts/Base.astro`.

## Project Structure

```
/
├── public/
│   ├── favicon.svg
│   └── materiale/          # Static files and documents
├── src/
│   ├── components/         # Reusable Astro components
│   ├── layouts/            # Page layouts
│   ├── pages/
│   │   ├── index.astro     # Homepage
│   │   ├── appunti/        # Notes section
│   │   └── posts/          # Blog posts
│   ├── themes/             # CSS theme files
│   └── config.ts           # Site configuration
├── astro.config.mjs        # Astro configuration
└── package.json
```

## Getting Started

1. **Clone or download this template**

    ```bash
    git clone https://git.phc.dm.unipi.it/phc/poisson-template-astro.git
    cd poisson-template-astro
    ```

2. **Install dependencies:**

    ```bash
    npm install
    # or
    bun install
    ```

3. **To edit the site locally:**

    ```bash
    npm run dev
    ```

4. **Edit the configuration:**

    - Update `src/config.ts` with your information
    - Modify the site title and other settings

5. **Add your content:**

    - Create posts in `src/pages/posts/`
    - Add notes in `src/pages/appunti/`
    - Include any static files in `public/materiale/`

## Content Creation

### Blog Posts

Create new markdown posts in `src/pages/posts/` with the following frontmatter:

```markdown
---
title: 'Your Post Title'
description: 'Brief description of the post'
tags: ['tag1', 'tag2']
publishDate: '2025-06-08'
draft: false
---

Your content goes here...
```

### Mathematical Content

The template supports mathematical expressions using [KaTeX](https://katex.org/):

- Inline math: `$E = mc^2$`

- Display math: `$$\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}$$`

## Deployment

### Deploy to Poisson Server

The template is pre-configured for deployment to the PHC Poisson server:

1. **Build for Poisson:**

    ```bash
    npm run build:poisson
    ```

2. **Update the Poisson configuration:**

    - Edit the `build:poisson` script in `package.json`
    - Replace `ncognome` with your actual username
    - Update the site URL accordingly

3. **Upload the built files:**

    - The build creates a `dist/` folder
    - Upload the contents to your Poisson web directory, for example using `scp`:

        ```bash
        scp -r dist/* ncognome@poisson.phc.dm.unipi.it:/home/ncognome/public_html/
        ```

        or with `rsync`:

        ```bash
        rsync -avz dist/ ncognome@poisson.phc.dm.unipi.it:/home/ncognome/public_html/
        ```

4. **Access your site:**

    - Visit `https://poisson.phc.dm.unipi.it/~ncognome/` to see your deployed site

### Deploy to GitHub Pages

For GitHub Pages deployment, follow these steps:

1. **Configure Astro for GitHub Pages:**

    Update `astro.config.mjs` to include your GitHub Pages settings:

    ```javascript
    export default defineConfig({
        site: 'https://yourusername.github.io',
        base: '/your-repo-name', // Only if not deploying to yourusername.github.io
        // ... other config
    })
    ```

2. **Create GitHub Action workflow:**

    Create `.github/workflows/deploy.yml`:

    ```yaml
    name: Deploy to GitHub Pages

    on:
        push:
            branches: [main]
        workflow_dispatch:

    permissions:
        contents: read
        pages: write
        id-token: write

    jobs:
        build:
            runs-on: ubuntu-latest
            steps:
                - name: Checkout your repository using git
                  uses: actions/checkout@v4
                - name: Install, build, and upload your site
                  uses: withastro/action@v3

        deploy:
            needs: build
            runs-on: ubuntu-latest
            environment:
                name: github-pages
                url: ${{ steps.deployment.outputs.page_url }}
            steps:
                - name: Deploy to GitHub Pages
                  id: deployment
                  uses: actions/deploy-pages@v4
    ```

3. **Enable GitHub Pages:**

    - Go to your repository's **Settings** → **Pages**
    - Select **GitHub Actions** as the source
    - Commit and push your changes

4. **Configure for custom domain (optional):**
    - Add a `CNAME` file in the `public/` directory with your domain
    - Update the `site` config to use your custom domain
    - Remove the `base` configuration

## Configuration Options

### Site Configuration

Edit `src/config.ts` to customize:

- Site title
- Post frontmatter types
- Other site-wide settings

### Build Scripts

- `npm run dev` - Start development server
- `npm run build` - Build for production
- `npm run build:poisson` - Build for Poisson server deployment
- `npm run preview` - Preview the built site

## Contributing

This template is designed for academic use at the University of Pisa. Feel free to customize and extend it for your needs.