- pardubicky.pirati.cz
Pirátská strana má své weby pro veřejnost statické a umístěné na vlastním serveru.
Samotné texty a data jsou umístěné v GIT repozitářích jako je tento. Repozitář je taková chytrá složka souborů. Chytrá je v tom, že si pamatuje veškerou historii umožňuje více lidem pracovat zároveň a slučovat jejich práci.
Repozitáře si můžete stáhnout (clone) na svůj počítač nebo k němu přistupovat pomocí githubu. Z githubu se repozitář stahuje na naše servery.
Když dojde ke změně dat tak se na naších serverech repozitář zkompiluje. K tomu se používá Jekyll, ten vezme soubory z aktulání verze repozitáře, přidá k nim soubory z jekyll-theme-pirati a vyrobí z nich samotné html & css, které pak čte webový prohlížeč.
Instalace na Fedora 25:
sudo dnf group install "C Development Tools and Libraries"
sudo dnf install ruby-devel
sudo dnf install rubygem-jekyll
Instalace Ubuntu 16.04:
sudo apt-get install ruby-dev gcc make libghc-zlib-dev
gem install rubygems-update
gem install jekyll bundler
bundle
Repozitář můžeme naklonovat do jakékoliv složky (nemusí být ve /var/www/).
Po stažení nové verze může být potřeba:
bundle install --path vendor/bundle
Spustění je pomocí
jekyll serve --watch --livereload, což stránku zkompiluje, spustí a ještě je stránka přístupná skrz localhost: http://127.0.0.1:4000
Popřípadě můžeme spustit jen: jekyll build, což do složky _site připraví kompletní web (ten můžeme otevřít z prohlíže pomocí klavesové zkratky ctrl+o).
instalujte docker podle návodu na váš operační systém (anglicky)
a ověřte že máte docker-compose official resources a spušteného demona.
Pak stačí:
docker-compose up
Za vylepšení tohoto návodu budeme rádi.
Gemfilese soubor "knihoven" které potřebuje Jekyll, nastavit v něm můžete např verzi thema které použijete.Gemfile.lockje pomocný soubor pro stejnou věc._config.ymlslouží jako hlavní návod pro Jekyll jak překládat, vyplňuji se v něm důležité texty a odkazy a taky nastavují některé parametry themaDockerfileadocker-compose.ymlslouží k lokálnímu spuštění webu.README.mdje tento text._siteavendorjsou složky viditelné jen při lokálním spuštení. V_sitejsou výsledné html stránky. Vvendorjsou uložené "knihovny".
- V
assetsbudete použítat primárně složkuimgkam patří fotky a obrázky. _posts,_people,_programobsahují soubory s články, lidmi a programovými body. Soubory jsou vždy ve formátu markdown a na vrhchu majíymlhlavičku která je ohraničená---.- Složka
_dataobsahuje soubory které jsou pouze tou hlavičkou. Kroměymlmohou obsahovat ijson. V_data/menu.ymlse nastavují odkazy v horní liště, menu i na spodu stránky.
Samotné stránky jsou v markdownu nebo v html (složitější struktura, např. vícesloupců apod)
index.htmlpopisuje titulní stránky- v dalších složkách jako je např
kontaktnebolidenajdeme popis stránek, které budou na example.pirati.cz/kontakt/ resp example.pirati.cz/lide/ krom indexu tam lze přidávat další stránky pokud např vkomunalni-volbypřidáte souborharmonogram.mdve správném formátu, tak vyrobíte stránku example.pirati.cz/komunalni-volby/harmonogram.html - obrázek se do stránky (i v markdown formátu) vkládá pomocí kódu
{% asset 'posts/jmeno_obrazku.jpg' alt='Popis obrázku' %}přičemž obrázek assets/img/posts/jmeno_obrazku.jpg musí existovat; kromě parametru alt je možné použít parametr magick pro úpravu obrázku, např.:magick:resize='200x', kompletní dokumentace je k dispozici zde
Rozlišujeme dva typy uživatelů. Prvními jsou lidé pouze zaregistrovaný na githubu může navrhnout změnu kdekoliv. Druhými jsou správci (collaborants) ti můžou rovnou přispívat a schvalovat změny.
Pro jednoduché weby doporučujeme mít pouze dva správce, jednoho 'editora' který na web dáva články informace a na začátku ho plnil a druhého technicky zdatného, který řeší problémy a dělat velké změny. Ostatní přispěvatelé mohou navrhovat změny.
Registrujte se tady jako username doporučuji zvolit reálné jméno a přidat i fotku. Usnadníte tím práci editorům a celkovou spolupráci pirátu na webech.
Jako je např. oprava gramatické chyby nebo přidání telefoního čísla.
Najděte si daný soubor. Vpravo nahoře obsahu toho souboru je symbol tužky. Kliknětě a navrhněte změny. Pokud není naprosto jasné co děláte tak do commit message dole připište zdůvodnění. Dejte navrhnout úpravy a pak schválit merge request. Tj. je třeba kliknout dvakrát.
Existuje ještě elegantní trik jak se dostat k editaci: přímo na samotném webu najít vpravo dole tlačítko navrhnout změnu.
Na githubu najeďte do složky, kam chcete soubor přidat, a klidněte na "create new file". Doporučuji si zároveň otevřít jiný soubor z dané složky, ať z něj můžete zkopírovat strukturu a vyměnit jenom data.
Fotky může přidávat pouze 'editor'. Fotky přidávejte v dostatečném rozlišení (lepší větší než menší). Web si fotky sám škáluje a ořezává podle toho, v jakém formátu je zrovna na daném místě potřebuje.
Fotky osob je dobré dodávat ve čtvercovém formátu, protože jejich profilové fotky, jsou vždycky čtvercové. Tím zamezíte nechtěným ořezům hlav lidí atp.
Pokud potřebujete použít stejnou funkcionalitu i na jiném místě ve vaší kopii webu, mrkntěte na použítí tady a tady.
Na hlavní stránce nahoře je pole "merge request" - tam se nachází seznam návrhů. Projděte si je, rozklikejte je a po kontrole můžete kliknout na "merge pull request" a následně "confirm merge".
Pokud děláte změny takto přes github, může dojít k chybě, které si hned nevšimnete. Proto je po změně potřeba zkontrolovat, že se vše povedlo. Nicméně buťte trpěliví, může trvat až pět minut než se změna projeví. Existují tři typy chyb:
- První je, že se něco viditelně rozbije - například zmizí kus textu a vy vidíte jen "tel" a za tím nic
- Druhý je, že se něco rozbije natolik, že web ani nejde přeložit. V tom případě zůstane ve staré verzi a vy nevidíte žádnou změnu.
- Třetí a nejhorší je, že nahrajete něco, co byste na pirati.cz vůbec neměli nahrávat. Tomu zabráníte jedině tak, že pečlivě kontrolujete commity a nepustíte dál žadnou změnu, které nerozumíte.
To, že něco pokazíte se může stát každému. Důležité je nebát si říct o pomoc a chybu napravit.
Tento web používá jekyll-pirati-theme. Cokoliv z něj jde přepsat. Používejte co nejnovějši verzi. Verze se nastavuje v Gemfile a je zmíněna i v assets části _config.yml.
Pokud chcete zasahovat do JS nebo CSS tak si přečtete dokumentaci thema
Pokud byste tuto šablonu chtěli využít pro tvorbu webu svého místního sdružení, změňte následující:
- v souboru
_config.ymlzměňte hodnoty v horní části (title, description, url) a odkazy pod tím - v adresáři
_peopleodstraňte naše lidi a místo toho založte vlastní - v adresáři
assets/img/peopledejte fotky vašich lidí - v adresáři
_postsodstraňte vzorový blogový příspěvek a dejte vlastní - v adresáři
assets/img/postsodstraňte naše fotky pro blogové příspěvky a dávejte vlastní - v souboru
kontakty/index.mdupravte doporučené kontakty, zároveň u jednoho člověka v people vyplňtecategorykontaktni_osoba - v souboru
lide/index.htmlupravte text a obsah stránkyO nas
Přidejte široký webový a úzký mobilní obrázek a nastavte parametry v _config.yml
V _config.yml vyplně adresu PiCe a obrázek. Následně v kontakty/index.html nastavte residence: yes.
To je trošku tricky nastavení, pro inspiraci se podívejte do jekyll-theme-pirati.
Pro vložení kaledáře existují dvě cesty:
- Jednoduchá: prostě zkopírujte adresu kalendáře pro vložení do stránky, takto vložený kalendář je zcela funkční, ale nevypadá úplně pěkně
- Složitější: zahrnuje nutnost získat Google Calendar API klíč, výhodou ovšem je, že kalendář bude vizuálně sladěný se zbytkem webu
V případě jednoduché varianty potřebujete pouze adresu pro embeddování.
Naleznete ji v nastavení kalendáře na Google Calendar webu. Tuto hodnotu vplňte
v _config.yml do pole calendar.page.
Složitější postup není ve skutečnosti nikterak komplikovaný. Budete potřebovat
získat ID kalendáře (napište ho do calendar.id), které je také k dispozici na
Google Calendar webu. Následně ještě budete potřebovat Google Calendar API key a
domluvit se se správcem webu aby vám ho zapnul.
API klíč získáte v Google Developer
Consoli. Nejprve si vytvořte nový
projekt (třeba example.pirati.cz). Poté je nutné přes "Enable APIs and services"
povolit pro projekt Google Calendar API. Poté si vytvořte samotný API klíč. To
provedete tak, že kliknete na "Create credentials" v sekci
Credentials. Jako typ
vyberete "API key" a výsledkem bude změť písmen a znaků, které tvoří samotný
klíč. Je vhodné pomocí "Restrict key" omezit adresy, na kterých klíč může být
používán, aby vám ho někdo neukradnul. V "Application restrictions" vyberte
"HTTP referers" a vyplňte všechny adresy, na kterých web chcete provozovat
(např. https://example.pirati.cz, vždy jedna na řádek). Pokud chcete udělat
klíč pro lokální vývoj (např. http://localhost:4000), doporučujeme si na to
udělat samostatný klíč a ten nikomu neukazovat aby se předešlo zneužití (protože
localhost vlastní každý).
Mějte na paměti, že s klíčem máte právo kromě čtení také věci editovat.
Jakmile máte platný klíč, tento klíč předejte správci, který s vámi řeší uvedení
webu do provozu. Řekněte mu, že potřebujete nastavit tzv. environment variable
GOOGLE_CALENDAR_APIKEY na hodnotu klíče, kterou jste předtím získali v
Developer Consoli. Poté bude váš kalendář vypadat jako např. na pardubickém
webu.
Implementace mapky návrhů byla ve verzi 6.1.0 jekyll-theme-piráti upravena, nyní je mapový podklad řešen přes službu Mapbox.
Abyste mapičku zobrazili, je nutné si tam vytvořit účet a následně získáte
access token. Ten pak při spuštění stránek poskytnete pomocí environment
variable MAPBOX_ACCESS_TOKEN. Následně můžete do kterékoliv stránky
přidat kód podobný tomuto:
{% if site.env.MAPBOX_ACCESS_TOKEN %}
<div class="__vue-root" data-app="IntentionMap" data-accesstoken="{{ site.env.MAPBOX_ACCESS_TOKEN }}" data-dataset="https://gist.githubusercontent.com/xaralis/f9711e5d12f971504d0753ba40c3d33e/raw/4a1701c64de5eb7ed6aa1538cb269022965d82d6/map.geojson" data-ideaform="https://goo.gl/forms/wKSPmWNDzgRiUxLN2"></div>
{% endif %}
Jak je vidět, potřebujete nějaký geojson soubor, který definuje jednotlivé položky
na mapě. Pro vytvoření mapového podkladu můžete využít libovolný GeoJSON
editor, např. http://geojson.io. Aby mapa záměrů správně fungovala,
měly by jednotlivé položky mapy mít následující atributy:
id- jedinečný identifikátor záměru, celé čísloname- definuje jméno záměru na mapěcategory- definuje kategorii záměrudescription- definuje detailní popis záměruimage(volitelné) - URL obrázku záměru
Pomocí atributu data-ideaform lze volitelně připojit i link na formulář, kam vám
veřejnost může zasílat své nápady.
Pokud chcete otestovat, jaké stránky se vám při nasazení vygenerují, spusťte následující příkaz:
JEKYLL_ENV=production bundle exec jekyll build
Výsledné stránky jsou uloženy v adresáři _site. Je vhodné následně ještě
spustit html-proofer pro ověření,
že všechny odkazy, které na webu máte, někam vedou:
bundle exec htmlproofer --assume-extension --disable-external --url-ignore "#,#fn:1" ./_site
Pokud tento příkaz selže, znamená to, že jste nejspíš někde uvedli špatnou adresu.
Můžete také využít příkaz build.sh, který obsahuje oba výše zmíněné příkazy:
./build.sh
Projděte si návod na git nebo knížku v čestine
Jekyll má velmi podrobnou dokumentaci. A při vývoji též doporučuji cheat sheet
Example web používá jekyll-pirati-theme. Cokoliv z něj jde přepsat. Používejte co nejnovějši verzi.
Technicky přesné dotazy můžete směřovat na TODO-issue-theme nebo redmine
Na cokoliv se zeptejte třeba na chatu
Ptejte se lidí okolo vás, kteří danou věc dělali, TO a dalších. Jak říkala moje prababička "Líná huba, holé neštěstí".