portulan/README.md

111 lines
3.4 KiB
Markdown
Raw Normal View History

2026-03-15 18:34:40 +01:00
# Oblic Parallels Home Website
2025-04-23 23:16:35 +02:00
2026-03-15 18:34:40 +01:00
## 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.
```json
{
"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
> ```json
> "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
```js
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
```astro
---
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.
2026-03-15 18:34:40 +01:00
## 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/`
2026-03-16 17:31:19 +01:00
- `scripts/`
- `data/` - Contains the configs to generate the website, each as a JSON file (contains cards, site name, colors, etc.)
2026-03-15 18:34:40 +01:00
- `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 |