poisson-template-astro/src/pages/posts/old/getting-started-with-astro.md

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

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.