Strona na wynos:
HTML bez internetu

Co właściwie znaczy „bez internetu”

Kotka.dev powstała ze zwykłego HTML, CSS i JavaScript. Potrzebujemy kopii, którą można rozpakować i pokazać bez uruchamiania serwera: z tymi samymi fontami, kocimi zdjęciami, notatkami i przełącznikiem języka. Sam HTML nie wystarczy: podłączone obrazy i skrypty pozostałyby osobnymi plikami.

Nasze rozwiązanie to kopia do przekazania dalej, a nie nowy format kodu źródłowego. Każda strona zawiera własne zasoby, a ZIP zbiera strony w jeden pakiet. Pliki do edycji pozostają osobno. Sprawdza się to w małej stronie statycznej, ale nie zamienia aplikacji serwerowej w aplikację offline.

Spakuj zależności, nie tylko stronę

1. Osadź style i skrypty
   Nasz skrypt pakujący wstawia CSS do elementu style, a każdy klasyczny skrypt do script. Kolejność się nie zmienia: dane notatek, interfejs, notatnik.
2. Osadź lokalne obrazy i fonty
   Bajty obrazów stają się adresami data URL. To samo dzieje się z adresami fontów i tekstur w CSS. Sprawdź też favicon i obrazy w atrybutach data, nie tylko duże zdjęcie na początku strony.
3. Zamień adresy wewnętrzne
   Link do notes.html powinien prowadzić do kotka-notes-standalone.html. Ścieżki artykułów w JavaScript wymagają takiej samej zamiany. Parametr języka i kotwicę sekcji trzeba zachować.

Data URL zawiera typ mediów i zakodowaną treść, na przykład data:image/webp;base64,…. Nie jest żądaniem pobrania zdalnego obrazu. Typ musi odpowiadać rzeczywistemu plikowi, a nie mylącej nazwie w adresie pobierania. MDN: data URL

Mała funkcja, która okazała się ważna

Sprawdzając okładkę PPC4 w spakowanym HTML, zauważyłyśmy, że jej dane WebP mają typ application/octet-stream. Przeglądarka mimo to wyświetlała obraz, ale nie warto było polegać na takim rozpoznawaniu. Teraz skrypt jawnie ustawia typy nowoczesnych formatów obrazów.

To rzeczywista funkcja z tools/build-standalone.py z importami potrzebnymi do samodzielnego uruchomienia. Wywołaj data_uri(pathlib.Path("assets/img/project-ppc4-hero.webp")), aby otrzymać ciąg znaków do użycia jako adres obrazu. Funkcja osadza jeden plik, nie przepisuje samodzielnie całej strony.

import base64, mimetypes, pathlib

def data_uri(path: pathlib.Path) -> str:
    # Windows MIME registry entries may omit modern image types.
    known_types = {".woff2": "font/woff2", ".webp": "image/webp", ".avif": "image/avif"}
    mime = known_types.get(path.suffix.lower()) or mimetypes.guess_type(path.name)[0] or "application/octet-stream"
    return f"data:{mime};base64,{base64.b64encode(path.read_bytes()).decode()}"

Baza mimetypes w Pythonie może zależeć od systemu operacyjnego, w tym rejestru Windows. Jawna tabela zapewnia przewidywalne typy tych trzech rodzajów zasobów w naszym pakiecie. Nadal zakładamy jednak, że rozszerzenia plików są poprawne. Python: mimetypes

W katalogu projektu Kotka.dev uruchom dwie poniższe komendy. Do budowania potrzebny jest Python 3, a do testów automatycznych — Node.js. Żadna z komend nie instaluje dodatkowych pakietów. Skrypt nadpisuje wygenerowane pliki HTML i ZIP w dist, dlatego edytuj strony źródłowe, nie te pliki.

python tools/build-standalone.py
node tools/check-notebook.cjs

Rozpakuj dist/kotka-dev-offline.zip, zostaw pliki HTML w jednym katalogu i otwórz kotka-dev-standalone.html. Każda strona zawiera własne zasoby, ale strony, do których prowadzą linki, są osobnymi plikami. Jeśli wyślesz tylko stronę główną, te przejścia nie zadziałają.

Sprawdź dokładnie tę kopię, którą wysyłasz

• Sprawdź wygenerowany HTML pod kątem pozostałych lokalnych ścieżek zasobów i nazw stron źródłowych. Nasze testy porównują też bajty osadzonych ilustracji projektów z oryginałami.
• Otwórz rozpakowaną stronę główną w docelowej przeglądarce bez połączenia z siecią. Przejdź do archiwum, artykułu i z powrotem; sprawdź, czy nie brakuje fontów lub obrazów.
• Przełącz UA / EN / PL i otwórz link. Offline nasze linki zawierają ?lang= (na stronie język jest częścią adresu, np. /pl/); opcjonalny local storage nie może być jedynym sposobem zachowania języka.
• Nie obiecuj za dużo: angielska treść artykułów jest zapisana w HTML, a tłumaczenia, wyszukiwanie i przełączanie notatek wymagają JavaScript.

Testy automatyczne sprawdzają wygenerowane ścieżki, osadzone zasoby i składnię skryptów. Sprawdzenie w przeglądarce przez localhost weryfikuje wygląd i interakcje. To przydatne, ale nie to samo co otwarcie pliku z dysku: test trybu plikowego w przeglądarce odbiorcy pozostaje osobnym krokiem końcowym.