Edukacyjny projekt o Wikipedii i etycznym SEO autorstwa Jakuba T. Jankiewicza. Odkryj mechanizmy największej encyklopedii świata i jej wpływu na twoją markę.

• Eleventy 3.1.5 — generator stron statycznych (szablony Liquid)
• PHP 8.3 — backend (SQLite, Mustache, JWT)
• subset-font — optymalizacja czcionki ikon (HarfBuzz WASM)
• HTML/JS minifikacja w produkcji (html-minifier-next, terser)
• Composer: mustache/mustache, wikimedia/minify, firebase/php-jwt

npm install          # instaluje zależności + pobiera czcionkę Material Symbols (postinstall)
npm run build        # buduje stronę (prebuild subsetuje czcionkę automatycznie)
npm run dev          # serwer deweloperski z live reload
npm run watch        # tryb watch bez serwera
npm run lint         # ESLint dla plików Markdown

docker compose up -d          # start na http://localhost:8080/
docker compose up -d --build  # przebuduj obraz
docker compose down           # zatrzymaj

Obraz: PHP 8.3-Apache, port 8080, volume mount katalogu _site/.

src/
├── _data/            # Dane: site.json, users.json, person.json, projects.json
├── _includes/        # Layouty (base, article, tool, page, blog) i partiale
├── blog/posts/       # Artykuły bloga (Markdown z YAML front matter)
├── tools/            # Interaktywne narzędzia SEO (generowane jako PHP)
├── static/           # CSS, obrazy, czcionki, favicony, wrappery PHP
├── card/             # Szablon SVG do social cards
├── llms.txt.liquid   # Indeks llms.txt
└── sitemap.liquid    # Sitemap XML

api/
├── subscribe/        # Subskrypcja newslettera (SQLite + weryfikacja email)
├── verify/           # Weryfikacja adresu email
├── contact/          # Formularz kontaktowy
├── lib/              # Wspólne narzędzia (email, sanityzacja, Umami)
└── templates/        # Szablony email (Mustache)

scripts/
├── download-font.mjs          # Pobieranie czcionki Material Symbols
├── subset-font.mjs            # Subsetting czcionki do WOFF2
├── validate-jsonld.mjs        # Walidacja JSON-LD w outputcie
├── validate-social-card.mjs   # Walidacja social cards SVG
├── indexnow.sh                # Zgłaszanie URL do IndexNow
├── install-hooks.sh           # Instalacja git hooks
└── hooks/pre-push             # Uruchamia watcher GitHub Actions

oferta/               # Osobny subprojekt (symlink)
_site/                # Output (NIE usuwać przy działającym Dockerze)

Czcionka Material Symbols Outlined (~10 MB) jest automatycznie subsettowana do ~230 KB WOFF2 zawierającego tylko ikony używane w projekcie.

1. npm install pobiera pełną czcionkę TTF do src/static/fonts/.source/ (gitignored)
2. npm run build (prebuild) skanuje src/ w poszukiwaniu nazw ikon, tworzy subset WOFF2 z przypiętymi osiami wariantów (FILL, GRAD, opsz)
3. Czcionka jest self-hosted — brak zewnętrznych requestów do Google Fonts

• Artykuły: src/blog/posts/*.md
• Front matter: title, date, tags, description, keywords, author, modified, faq
• Autorzy zdefiniowani w src/_data/users.json (klucz: nick, np. jcubic)
• Social cards generowane automatycznie z szablonu SVG (wymaga fontu Lovelo w CI)

Interaktywne narzędzia w katalogu src/tools/, generowane przez Eleventy jako pliki PHP (layout tool.liquid). Każde narzędzie wymaga config.json z kluczem API (gitignored).

• /tools/books/ (pl) i /en/tools/books/ (en) — generator cytowań do Wikipedii (Google Books API), dwujęzyczny. Wspólny rdzeń to partial partials/books-tool.liquid i skrypt /js/books.js; każda wersja językowa to cienki wrapper (index.liquid, en.liquid) różniący się tylko front matterem. Tłumaczenia, mapowania pól szablonów (Cytuj książkę→Cite book, Cytuj→Citation), host wiki i teksty siedzą w src/_data/books.json. Osobne strony dają własny <title>, meta i hreflang. Nowy gość bez wybranego języka jest wg nagłówka Accept-Language przekierowywany ze strony domyślnej (pl) na swój język (brak dopasowania → angielski); dowolny query string (np. ?lang=pl) wyłącza przekierowanie, więc każdy może zobaczyć dowolny język.
• /tools/graf-wiedzy/ — wyszukiwarka wpisów w Grafie Wiedzy Google (Knowledge Graph API)
• /tools/status/ — panel diagnostyczny chroniony JWT (unlisted, wymaga jwt_secret w config.json)

1. Utwórz klucz w Google Cloud Console z dostępem do odpowiedniego API.
2. Utwórz plik src/static/tools/<narzędzie>/config.json z kluczem API jako wartością JSON string (np. "AIzaSy...").
3. Plik config.json jest w .gitignore — nie będzie commitowany.

Na środowisku CI/CD narzędzia działają bez klucza API — wyświetlają komunikat o braku konfiguracji.

• POST /api/subscribe/ — subskrypcja newslettera (SQLite + weryfikacja email)
• GET /api/verify/ — weryfikacja adresu email tokenem
• POST /api/contact/ — formularz kontaktowy (wysyła plain-text email)

Wszystkie formularze używają honeypot do ochrony przed spamem. W środowisku lokalnym (bez sendmail) emaile zapisywane są do api/mail/index.html.

• JSON-LD: schematy Organization, Person, BlogPosting, SoftwareApplication, FAQPage
• Sitemap: generowany dynamicznie (src/sitemap.liquid), wyklucza strony z unlisted: true
• robots.txt: zezwala na GPTBot, ClaudeBot, DeepSeekBot, Google-Extended, Applebot-Extended
• IndexNow: scripts/indexnow.sh zgłasza URL-e do natychmiastowej indeksacji (wymaga INDEXNOW_KEY)
• Social cards: automatyczna generacja PNG dla artykułów i narzędzi

Strona serwuje pliki tekstowe dla modeli językowych:

• /llms.txt — indeks z linkami do plików sekcji
• /llms-full.txt — pełny zrzut treści strony
• /blog/{slug}.md — markdown każdego artykułu
• Content negotiation: nagłówek Accept: text/markdown zwraca wersję Markdown
• HTTP Link header reklamuje sitemap i llms.txt

• Produkcja: push do master → GitHub Actions buduje + deploy przez SSH
• Dev: push do dev → deploy na serwer deweloperski
• CI pipeline: lint → instalacja zależności → walidacja social cards → build → walidacja JSON-LD → deploy (SSH)
• Hosting: MyDevil.net (Apache)

./scripts/install-hooks.sh    # instaluje hooki z scripts/hooks/

• pre-push: uruchamia watch-actions.sh w tle — monitoruje GitHub Actions i odgrywa dźwięk po zakończeniu

Copyright (C) 2026 Jakub T. Jankiewicz

Treść (artykuły, teksty) udostępniona na licencji CC-BY-SA 4.0.

Kod źródłowy narzędzi (src/tools/) udostępniony na licencji AGPL-3.0 — patrz plik LICENSE.