portulan/README.md

Oblic Parallels Home Website

About

Contains the source code of the Home OP website. Now uses Astro instead of the old static website !

How to use it

If you want to use this project for yourself, you'll first want to edit the configuration file located at src/data/content.json. The file should look like this, don't hesitate to take the provided template file to make yours.

{
  "website_title": "Website Title",
  "website_logo": "https://...",
  "website_status_link": "https://...",
  "colors": {
    ...  // Optional
  },
  "cards": [
    {
      "title": "Card One",
      "icon": "https://...",
      "description": "First description",
      "link": "https://..."
    },
    {
      "title": "Card Two",
      "icon": "https://...",
      "description": "Second description",
      "link": "https://..."
    }
  ]
}

Note

You can also use a relative path for your icons like that

 "icon": "../assets/some-icon.svg",

Optimized image loading

I would recommend to use only SVGs in your image links if possible. If it's not possible and that you want to optimize the loading time, you should use the lazy image loading.

Warning

This feature is not implemented yet and you'll have to go manually inside the src/components/ folder to make modifications. In order to use the lazy image loading you'll need to allow your source domain inside astro.config.mjs like following

import { defineConfig } from 'astro/config';

export default defineConfig({
  image: {
    // Add your domain 
    domains: ['resources.example.com'], 
  },
});

Then for each component that uses a raster image (PNG, JPG...) use the following syntax

---
import { Image } from 'astro:assets';
const { title, icon, ... } = Astro.props;
---

<Image 
  src={icon} 
  alt={title} 
  width={160} 
  height={160}
  quality="high"
  format="webp"
  loading="eager"
/>

Note that in this case, it would be a good idea to store your images in the assets folder an to access them using their relative path to let astro generate what it needs to fully take advantage of this feature.

Structure

Project

• src/* - Source code (components, pages, styles, images, etc.)
• public/* - Non-code, unprocessed assets (fonts, icons, etc.)
• package.json - Project manifest
• astro.config.mjs - Astro configuration file
• tsconfig.json - TypeScript configuration file

src/

• assets/
• components/
• layouts/
• pages/
• scripts/
• data/ - Contains the configs to generate the website, each as a JSON file (contains cards, site name, colors, etc.)
• styles - default CSS style sheets and custom themes

Build

This project is meant to be used with pnpm, but you can use whatever package manager you want (at your own risk).

Commands

Command	Action
pnpm install	Installs dependencies
pnpm dev	Starts local dev server at localhost:4321
pnpm build	Build your production site to ./dist/
pnpm preview	Preview your build locally, before deploying
pnpm astro ...	Run CLI commands like astro add, astro check
pnpm astro -- --help	Get help using the Astro CLI