---
layout: '@/layouts/Post.astro'
title: Getting Started with Poisson Astro Template
publishDate: 2025-06-07
description: | 
  This article will guide trough the configuration of the Astro template for Poisson
tags: ['astro', 'web-development', 'javascript', 'performance', 'static-site']
---

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