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.

License

This template is provided as-is for educational and academic purposes.