poisson-template-astro/README.md

Poisson Blog Template

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

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

2. Install dependencies:

   npm install
   # or
   bun install
   

3. To edit the site locally:

   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:

---
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:

• 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:

   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:

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

     or with rsync:

     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:

   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:

   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.