📘 FEDIA.EU / fs — Пълен наръчник

Статичен сайт (Astro 5 + Tailwind + Content Collections). Накрая се качва само папка dist/ — както при чист HTML. Cloudflare Pages не се интересува дали източникът е бил HTML или Astro.

---

1. Бърз старт

npm install
npm run dev          # http://localhost:4321
npm run build        # → папка dist/
npm run preview      # преглед на production build локално

Команда	Какво прави
npm run dev	dev сървър с hot reload
npm run build	генерира статични файлове в dist/
npm run preview	сервира dist/ локално (както online)

Node: >= 18.14

---

2. Структура на проекта

fs/  (или fedya007/, fedia-astro/)
├── public/                 # статични файлове → копират се 1:1 в dist/
│   ├── books/              # PDF книги
│   ├── covers/              # корици
│   ├── favicon.*
│   ├── fed.webp
│   └── robots.txt
├── scripts/
│   ├── html_md_to_real_md.py   # HTML-в-.md → истински Markdown
│   └── url_to_md.py            # сваля статия от URL → .md
├── src/
│   ├── content/            # ★ СТАТИИТЕ (Markdown)
│   │   ├── docker/*.md
│   │   ├── linux/*.md
│   │   ├── proxmox/*.md
│   │   ├── wsl/*.md
│   │   ├── docs/                 # наръчник(ци)
│   │   └── scripts/               # скриптове (.md)
│   ├── content.config.ts   # schema за frontmatter / колекции
│   ├── components/
│   │   ├── Nav.astro           # главно меню
│   │   ├── GuideNav.astro      # prev/next между части
│   │   └── RelatedPosts.astro  # „Може да ви е интересно"
│   ├── data/
│   │   ├── nav.ts              # меню + динамични guide parts
│   │   ├── articles.ts         # related карти
│   │   └── recommendations.ts  # страница Препоръчвам
│   ├── layouts/
│   │   ├── BaseLayout.astro    # HTML shell, footer, meta
│   │   └── GuideLayout.astro   # layout за статии (hero, author, tags)
│   ├── pages/
│   │   ├── index.astro
│   │   ├── preporychvam.astro
│   │   ├── knigi/knigi.astro
│   │   ├── en/index.astro
│   │   ├── 404.astro
│   │   ├── narachnik.astro       # страница на наръчника
│   │   ├── scripts.astro         # каталог на скриптовете
│   │   ├── scripts/[slug].astro  # шаблон за отделен скрипт
│   │   ├── [slug].astro          # Docker URL-и: /docker, /docker-architecture…
│   │   ├── linux/[slug].astro    # /linux/…
│   │   ├── prox/[slug].astro     # /prox/…
│   │   └── wsl/[slug].astro      # /wsl/…
│   └── styles/global.css       # Tailwind + custom стилове
├── astro.config.mjs
├── tailwind.config.mjs
├── package.json
└── dist/                   # ← това се качва / се билдва от CI

---

3. Къде пипаш какво

Искам да…	Файл / място
Редактирам статия	src/content/<серия>/<slug>.md
Нова статия в поредица	нов .md в същата папка + frontmatter
Нов скрипт	src/content/scripts/<ime>.md
Смяна на менюто	src/data/nav.ts → mainNav
Prev/next между части	автоматично от order/part в frontmatter + nav.ts
Related карти	src/data/articles.ts
Страница Препоръчвам	src/data/recommendations.ts
Книги (PDF линкове, текст)	src/pages/knigi/knigi.astro
Каталог на скриптове	src/pages/scripts.astro
Наръчник (тази страница)	src/content/docs/narachnik.md → src/pages/narachnik.astro
Начална страница	src/pages/index.astro
English	src/pages/en/index.astro
404	src/pages/404.astro
Глобални стилове	src/styles/global.css
Layout / footer / SEO meta	src/layouts/BaseLayout.astro
Hero, author, tags над статия	src/layouts/GuideLayout.astro
PDF / картинки статични	public/ (път /books/..., /covers/...)
Снимка към статия (hero)	src/content/<серия>/images/ + heroImage във frontmatter

URL-и (не ги сменяй без redirect):

Колекция	Примерен URL
docker	/docker, /docker-architecture, /dockerfile…
linux	/linux/linux-foundation, /linux/security…
proxmox	/prox/uvod, /prox/vm…
wsl	/wsl/uvod, /wsl/nastroika…
скриптове	/scripts, /scripts/<slug>
наръчник	/narachnik

---

4. Frontmatter

4.1. Статия (docker/linux/proxmox/wsl)

---
title: "Част 1: Linux — основата | Федя Серафиев — FEDIA.EU"
description: "Кратко SEO описание (1–2 изречения)."
series: linux
author: "Федя Серафиев"
pubDate: 2024-08-01
updatedDate: 2026-09-08
lang: bg
draft: false
part: 1
order: 1
tags: ["linux", "sysadmin"]
categories: ["Linux"]
heroImage: "./images/linux.webp"
heroImageAlt: "Linux терминал"
---

# Част 1: Linux — основата

Текст на **Markdown**.

## Подзаглавие

- списък
- още

`inline code`

​```bash
echo "code block"
​```

Поле	Задължително	Бележка
title	да	и за <title> / OG
description	да	meta description
series	да	docker | linux | proxmox | wsl
author	не	default: Федя Серафиев
pubDate	не	дата на публикуване
updatedDate	не	ако си обновявал
lang	не	bg / en
draft	не	true = не се билдва и не е в GuideNav
part / order	препоръчително	подредба в поредицата
tags / categories	не	показват се в layout
heroImage	не	локално ./images/... или URL

Снимки за hero: src/content/linux/images/cloudflare.webp и във frontmatter heroImage: "./images/cloudflare.webp".

4.2. Скрипт (src/content/scripts/*.md)

---
title: Заглавие
description: Описание
version: 1.0.0
author: Федя Серафиев
category: Автоматизация
tags: ['tag1', 'tag2']
date: 2026-09-10
featured: false
---

# Заглавие

Съдържание...

---

5. Скриптове за миграция на съдържание

5.1. HTML вътре в .md → истински Markdown

pip install beautifulsoup4 markdownify
python scripts/html_md_to_real_md.py
python scripts/html_md_to_real_md.py src/content/linux
python scripts/html_md_to_real_md.py --force   # всички файлове

5.2. Статия от live URL → .md

pip install requests beautifulsoup4 markdownify
python scripts/url_to_md.py https://fedia.eu/linux/linux-foundation
# → md_output/<slug>.md  → копираш в src/content/<series>/

---

6. Изчистване на кеша (когато нещо не се обновява)

rm -rf node_modules/.astro .astro dist
npm run dev

---

7. Deploy: GitHub → Cloudflare Pages

Astro build = статични HTML/CSS/JS в dist/. Същият модел като при HTML сайт; Cloudflare само билдва вместо теб.

7.1. Първоначален push в GitHub

git init   # ако още няма repo
git add .
git commit -m "FEDIA.EU Astro site"
git remote add origin https://github.com/<user>/<repo>.git
git branch -M main
git push -u origin main

Не качвай в git (ако има .gitignore — ок): node_modules/, dist/ (CI ще го генерира), .env с тайни.

Препоръчителен .gitignore:

node_modules/
dist/
.astro/
.env
.DS_Store
md_output/

7.2. Настройка на Cloudflare Pages

1. Cloudflare Dashboard → Workers & Pages → Create → Pages → свържи GitHub repo
2. Настройки на build:

Поле	Стойност
Framework preset	Astro (или None)
Build command	npm run build
Build output directory	dist
Root directory	/ (или подпапката, ако repo-то е монорепо)
Node version	18 или 20 (Environment variables → NODE_VERSION=20)

3. Save and Deploy
4. След успех: Custom domain → fedia.eu

7.3. Redirects (стари .html линкове)

Файл public/_redirects или Cloudflare Pages → Redirects:

/docker.html  /docker  301
/linux/linux-foundation.html  /linux/linux-foundation  301

(Добави само ако реално има стари .html URL-и в Google/bookmarks.)

---

8. HTML vs Astro — губиш ли нещо при смяна?

Не за посетителя.

	Стар HTML	Astro
Online	статични файлове	статични файлове (dist/)
Cloudflare	качваш файлове / Pages	Pages build → dist/
URL-и	същите (ако ги запазим)	същите
Скорост	добра	често по-добра (билднат CSS, без Tailwind CDN)

Ти като автор: редактираш .md + npm run build (или push → автоматичен build), вместо ръчно да пипаш десетки HTML файлове.

---

9. Git — ежедневна работа

9.1. Проверка на статуса

git status               # какво е променено
git status -s            # кратък формат
git branch               # в кой клон си
git log --oneline -10    # последни 10 commits

9.2. Commit и push

git add .                                    # добави всички промени
git add src/content/scripts/нова-статия.md   # или конкретен файл
git commit -m "Add: Нов скрипт за backup"
git push

9.3. Работа с клонове

git checkout -b feature/нова-функция   # нов клон
git branch -a                          # всички клонове
git checkout main                      # върни на main
git merge feature/нова-функция         # слеи клон
git branch -d feature/нова-функция     # изтрий клон

9.4. Спасяване при грешка

git checkout -- .              # откажи неозапазените промени
git reset --soft HEAD~1        # откажи последен commit (запази промените)
git reset --hard HEAD~1        # откажи последен commit (ИЗТРИВА промените!)
git stash                      # скрий промените временно
git stash pop                  # върни ги
git revert HEAD                # безопасен откат на вече push-нат commit

9.5. Типични commit съобщения

git commit -m "Add: Нов скрипт за Docker backup"
git commit -m "Fix: Поправен линк в навигацията"
git commit -m "Update: Обновен README"
git commit -m "Remove: Изтрит стар скрипт"
git commit -m "Docs: Добавена документация"
git commit -m "Style: Форматиране на CSS"
git commit -m "Refactor: Преименувани променливи"

---

10. NPM команди

npm install                  # инсталирай зависимости
npm install пакет-име        # конкретен пакет
npm install --save-dev ИМЕ   # само за разработка
npm update                   # обнови всички
npm outdated                 # провери остарели
npm info astro               # информация за пакет

---

11. Търсене и проверка

find src/content/scripts -name "*.md"        # всички .md файлове
ls src/content/scripts/*.md | wc -l          # брой
grep -r "docker" src/content/scripts/        # търси текст
head -15 src/content/scripts/ИМЕ.md          # провери frontmatter
tree src/ -L 3                               # структура
npm run build 2>&1 | grep -i "error"         # провери за грешки

---

12. Типични сценарии

Сценарий 1: Добавяне на нов скрипт

cd /mnt/c/Users/fedia/Desktop/fs
nano src/content/scripts/docker-cleanup.md
# постави шаблона (виж 4.2)
# Ctrl+O → Enter → Ctrl+X

# ако dev сървърът работи → виж http://localhost:4321/scripts/
# ако НЕ се появи:
rm -rf node_modules/.astro .astro
npm run dev

git add src/content/scripts/docker-cleanup.md
git commit -m "Add: Docker cleanup скрипт"
git push

Сценарий 2: Промяна на дизайна

nano src/pages/scripts.astro
# промени CSS-а в <style> блока
# Ctrl+O → Enter → Ctrl+X

# hard refresh: Ctrl + Shift + R

git add src/pages/scripts.astro
git commit -m "Style: Обновен дизайн на каталога"
git push

Сценарий 3: Нещо се счупи

git status              # виж какво е променено
git diff                # виж разликите
git checkout -- .       # откажи неозапазените промени

# ако си направил лош commit:
git reset --hard HEAD~1    # ВНИМАНИЕ: изтрива промените!

# ако си направил лош push:
git revert HEAD
git push

Сценарий 4: Pull от друга машина

cd /mnt/c/Users/fedia/Desktop/fs
git pull
rm -rf node_modules/.astro .astro dist
npm run dev

Сценарий 5: Нова статия / промяна на съдържание (общ цикъл)

# 1. Пишеш/редактираш src/content/.../*.md
# 2. npm run dev — гледаш локално
npm run dev

# 3. git add → commit → push
git add .
git commit -m "Fix: overwrite sitemap.xml with correct trailing-slash version"
git push

# 4. Cloudflare Pages билдва автоматично

---

13. Често срещани проблеми

Симптом	Решение
Build: грешка за { в съдържание	в MD не е проблем; ако е .astro страница — escape {'{'}
# заглавие „не се вижда”	вече е оправено в global.css (.article-content h1)
Няма стилове	npm run build / hard refresh; Tailwind е през @astrojs/tailwind, не CDN
Статия липсва online	draft: true или файл извън src/content/<series>/
Docker prev/next води към /docker/docker	оправено в nav.ts — вземи актуалния файл
PDF 404	файлът трябва да е в public/books/ и линкът /books/ime.pdf
Cloudflare build fail	провери Node 18+, npm run build локално първо
Скрипт/статия не се появява след добавяне	изчисти кеша (виж т. 6)

---

14. Чеклист преди първо качване (initial deploy)

npm install
npm run build
npm run preview

После отвори и провери:

• / начална
• /docker + prev/next към следваща част
• /linux/linux-foundation — заглавия # / ## изглеждат нормално
• /linux/astro-cloudflare-pages — hero снимка
• /prox/uvod, /wsl/uvod
• /knigi/knigi — PDF линковете свалят файлове
• /preporychvam — външни линкове (spirachki, itpraktika)
• /en
• /scripts — каталогът се зарежда
• /narachnik — наръчникът се зарежда
• умишлен грешен URL → 404 страница
• меню (desktop + мобилен hamburger)
• npm run build без грешки в терминала

Ако всичко отгоре е зелено → качвай спокойно (GitHub + Cloudflare Pages).

15. Чеклист преди всеки push (ежедневен)

• npm run dev работи без грешки?
• Новото съдържание се появява на съответната страница?
• Отделната страница/скрипт се отваря правилно?
• Бутони / интерактивни елементи работят (напр. „📋 Копирай”)?
• npm run build минава без грешки?
• git status показва само това, което искаш?

Ако всичко е ✅ → git push 🚀

---

16. Полезни пътища (резюме на един екран)

Статия              → src/content/<series>/<slug>.md
Скрипт              → src/content/scripts/<slug>.md
Наръчник            → src/content/docs/narachnik.md
Меню                → src/data/nav.ts
Препоръчвам         → src/data/recommendations.ts
Related             → src/data/articles.ts
Книги               → src/pages/knigi/knigi.astro
Каталог скриптове   → src/pages/scripts.astro
Шаблон скрипт       → src/pages/scripts/[slug].astro
Стилове             → src/styles/global.css
Колекции (schema)   → src/content.config.ts
Layout              → src/layouts/BaseLayout.astro
Build изход         → dist/
Скриптове (python)  → scripts/

Край на наръчника.