Content first, code second

A personal site should be easy to change while the idea is still fresh. If updating one paragraph requires opening a component, checking layout code, and trying not to break styles, the workflow is already too heavy.

Why Markdown is enough

This portfolio does not need a database yet. It needs a clean way to write, review, translate, and publish small pieces of content.

Markdown is enough for that. It is readable in the editor, friendly to Git diffs, and portable if the site changes framework later. It also makes the writing feel less like configuration and more like writing.

That matters because most portfolio updates are not technical features. They are content changes:

• a project summary becomes sharper
• an external link changes
• a new blog post is published
• a French translation needs a better sentence
• an old experiment becomes less important

Those changes should be small.

src/content/
├─ blog/
│  ├─ en/
│  └─ fr/
├─ pages/
│  ├─ en/
│  └─ fr/
└─ site/
   ├─ en/
   └─ fr/

The clean split

The codebase follows a simple split:

• content files describe what the page means
• Astro pages decide which content to load
• components render repeatable structure
• CSS files handle the visual system

This keeps the code from becoming a pile of text strings. It also keeps the Markdown from knowing too much about the interface.

For example, a project entry can store a name, summary, stack, and links. The card layout can change later without rewriting the project itself.

Change	File to edit	Code touched?
Update a project summary	src/content/pages/*/work.md	No
Publish a blog post	src/content/blog/{locale}/new-post.md	No
Add a new card layout	component + CSS	Yes
Translate footer text	src/content/site/{locale}/footer.md	No

Why it helps localization

Once the site supports French and English, content structure becomes even more important. Each language can have its own Markdown file, but the route system and components stay shared.

That means translation is not a special case. It is part of the content workflow.

When another language is added later, the same pattern can continue: create the localized content folder, add the translations, and let the shared UI render it.

The trade-off

This approach is not magic. If the content model changes, the schema has to change too. That is a good constraint. It forces the site to define what kind of content it actually supports.

For a portfolio, that trade-off is worth it. The site stays static, fast, and easy to deploy, while the content remains flexible enough to grow.