search

machal / prirucka

Texty o technikách a technologiích moderní webové kodéřiny.
http://www.vzhurudolu.cz/prirucka/css3
20 stars 7 forks source link

readme

Příručka pro VzhůruDolů.cz

Texty o technikách a technologiích moderní webové kodéřiny.

Opravy, bugreporty, změny jsou vítány: github.com/machal/prirucka/issues.

Používáme Markdown Extra

Pravidla psaní

Texty zde vložené se čtou nebo mohou být čteny na různých místech:

  1. V tomto veřejném repozitáři.
  2. V Příručce na VzhůruDolů.cz: vrdl.cz/prirucka/css3.
  3. V e-boocích: vrdl.cz/ebooky
  4. V tištěných knihách.

Před každým zveřejněním na těchto místech prochází Markdown obsah určitými transformacemi a proto je potřeba držet se jednotného způsobu psaní.

V prvé řadě je potřeba psát obecně ve stylu například „v době psaní tohoto textu“, nikoliv „v době psaní tohoto článku“.

Název článku

Měl by být maximálně stručný, stroze technický. Primárně pro e-booky a jejich obsah. Např. e-book o AMP je dost komplexní, takže se do něj obsah knížky (TOC) vkládá na úrovni podkapitol, tedy samotných článků.

Šťavnatější a pro SEO upravené názvy pro online výskyt na Vzhůru dolů se používají názvy vložené do administrace při zveřejnění textu.

Formátování

Pro ebooky je lepší co nejjednodušší formátování, proto:

Odkazy

V textu odkazujeme obecně jen interně - přímo na Markdown soubory, které jsou v eboocích, externí jako celé url. Aby to v ebooku bylo jasné. Na co lze klikat a co vede ven. A taky kvůli případnému tisku odkazy ven pomocí celých url.

A pozor, zápis odkazu na konci odstavce nesmí začínat http:// např. [vrdl.cz…]. Vždy [vrdl.cz…]. Jednak kvůli stručnosti a jednak kvůli možným chybám v XHTML pro ePub.

Pozor také na to, že ne vždy je čtenář online. K důležitým odkazům tedy dávat do textu shrnutí.

Komponenty ve stránce

Schéma barev pro obrázky a ilustrace

Pravidla pro obrázky

Vkládání obrázků

Standardně vkládáme jako obrázek:

![Podíl mobilů](../dist/images/original/statistika-mobily.jpg)

Alternativně s popiskem jako <figure>:

<figure>
<img src="https://github.com/machal/prirucka/raw/master/./dist/images/original/todo.jpg" width="1600" height="900" alt="…">
<figcaption markdown="1">
*Google PageSpeed Insights zobrazí skóre webu, ale také rovnou návrhy na vylepšení*
</figcaption>
</figure>

Popisek (figcaption) není potřeba uvádět jako: „Obrázek: …“, protože je ve všech místech výskytu vizuálně oddělený od zbytku obsahu.

Pro alternativní zobrazení s popiskem vedle obrázku stačí přidat třídu figure-thirds.

Jiný poměr stran než 16 : 9

Hlavně kvůli AMP a layoutu v <amp-img> je potřeba u obrázků, které mají jiný poměr stran než 16 : 9, uvádět rozměry explicitně. Stačí poměr stran. Například pro výškou poloviční obrázky – 32 : 9:

<p><img src="https://github.com/machal/prirucka/raw/master/./dist/images/original/pagespeed-insights-skore.jpg" width="1920" height="540"  alt="PageSpeed Insights Skóre"></p>

Jen pozor:

Široké obrázky

Zabezpečí to třída .img-wide, ale pak už tam nesmí být <figure>.

<img … class="img-wide">

Hodí se to na všechna možná podrobnější schémata atd.

Video

Vložení z YouTube

Nejlepší způsob je kvůli cookies a potřebnému souhlasu pomocí prostého odkazu:

Podívejte se na video „AMP: ekosystém: Co je AMP Cache, co Optimizer a co Viewer?“.

YouTube: youtu.be/l751Or7iZCA

Do budoucna to případně budu nahrazovat nějakým slušným embedem.

Následující je nyní přežité a z markdownů odstraněné:

Dále je možné vložení pomocí HTML kódu. Markdown je tady nespolehlivý:

<p class="video">
Video: <a href="https://www.youtube.com/watch?v=VN8CFG-YajE">BrowserStack</a> ~ Jak testovat web ve všech prohlížečích a nemuset řešit virtuály a emulátory.
</p>

Pro případné přímé vložení iframe z Youtube je na webu potřeba obalit jej pomocí .rwd-media. Jinak se nechová responzivně k velikost okna:

<div class="rwd-media">
<iframe width="560" height="315" src="https://www.youtube.com/embed/eywi0h_Y5_U" frameborder="0" gesture="media" allow="encrypted-media" allowfullscreen></iframe>
</div>

Komponenta .rwd-media standardně dělá poměr stran 16 : 9, ale lze přidat různé modifikátory, např. .rwd-media--160-45 pro poloviční výšku. Viz stejnojmenná komponenta u Vzhůru dolů webu.

Vložení MP4

Alternativně můžeme vložit přímo video, se zdrojem na Cloudinary. viz např. content/img-pomer-stran.md.

Ale je potřeba vložit jako MP4, protož např. Safari WEBM neumí. Při vytváření v QuickTime stačí po uložení do .mov přejmenovat koncovku na .mp4. Pokud video stahuješ ze zdrojů od Googlu, stahuj v Safari, tam se to uloží do MP4.

Nedávej autoplay, žere ti to kredit na Cloudinary.

<div class="rwd-media">
  <video muted controls width="1600" height="900">
    <source src="https://res.cloudinary.com/vzhurudolu-cz/video/upload/v1587737526/vzhurudolu-video/img-aspect-ko_gdcr9f.mp4"
      type="video/mp4">
  </video>
</div>

Citace

Týká se i vkládání obsahu v embedech od Twitteru, které ruším od roku 22 kvůli cookie liště.

Zjistil jsem, že v Markdownu je možné vkládat krásnou citaci i s uvedením zdroje:

Víte jaká je nejlepší cookie lišta? Žádná!

– Z ohlasů na Twitteru

CodePen s ukázkou

Ukázky vkládáme jako běžný odstavec v Markdownu:

CodePen: [cdpn.io/e/XzYzXJ](https://codepen.io/machal/pen/XzYzXJ?editors=1100)

Na webu se to pak přepíše vkládaného <iframe>.

Style guide pro CodePeny

Tabulka

Jednodušší:

| Prvek      | Vzhled | Klik/touch |
|------------|:------:|:----------:|
| `<span>`   |  +     |            |

Pro dvoustavové značky v tabulkách používáme +, protože je dostupné ve všech písmech, kterými se obsah vykresluje.

Složitější tabulky ideálně jako <figure>:

<figure>

<div class="rwd-scrollable prop-table f-6"  markdown="1">
| Prvek      | Vzhled | Klik/touch | Focus | Význam | Mezerník |
|------------|:------:|:----------:|:-----:|:------:|:--------:|
| `<span>`   |  +     |      +     |       |        |          |
| `<a>`      |  +     |      +     |    +  |        |          |
| `<button>` |  +     |      +     |    +  |    +   |      +   |
</div>  

<figcaption markdown="1">
*Tabulka: Přidáním třídy můžeme nastavit vzhled tlačítka na jakýkoliv element*
</figcaption>

</figure>

Dále je možné třídami sjednotit šířku prvního sloupce:

Podcast

Vložení opět pomocí HTML kódu.

<p class="podcast">
Podcast: <a href="https://soundcloud.com/vzhurudolu/s-robinem-pokornym-o-css-v-js" data-id="296642310">S Robinem Pokorným o CSS v JS</a>
</p>

Související články

Vložení opět pomocí HTML kódu.

<div class="related" markdown="1">
- [S Robinem Pokorným o CSS v JS](/blog/link)
- [Nějaký další odkaz na článek z příručky](/prirucka/link)
</div>

Jednotlivé články zatím vkládáme takto:

→ Související: Vkládání JavaScriptu jako async, defer a type="module"

Související informace

Obrázek vlastnosti, stručná vysvětlivka, odkazy na další příručky a případně živé URL. Vkládáme pomocí HTML vždy za první odstavec definující vlastnost:

<div class="connected" markdown="1">

<!-- Obrázek -->
![CSS vlastnost gap](../dist/images/medium/vdlayout/schema-css-gap.jpg)

<!-- Popisek -->
`gap` je mezera mezi vnitřními prvky layoutu.

<div class="web-only" markdown="1">

<!-- Související příručky -->
Vlastnost `gap` je možné použít ve všech layoutech – v  [CSS gridu](css-grid.md), [flexboxu](css-flexbox.md), [multicol](css-multicolumn.md). Patří však do specifikace [CSS Box Alignment](css-box-alignment.md).

</div>

<div class="ebook-only" markdown="1">

<!-- Odkaz na živé URL pro knížky -->
→ [vrdl.cz/p/css-gap](https://www.vzhurudolu.cz/prirucka/css-gap)

</div>

</div>

Seznam vlastností

Možné to je, viz /prirucka/css-flexbox:

Příklad:

<div class="reference-items">

  <div role="article" class="reference-items-item">
    <h4><a href="https://github.com/machal/prirucka/blob/master/css-align-items.md">align-items</a></h4>
    <p><a href="https://github.com/machal/prirucka/blob/master/css-align-items.md"><img src="https://github.com/machal/prirucka/raw/master/./dist/images/small/vdlayout/css-align-items-schema.jpg" alt="Vlastnost align-items" /></a></p>
    <p>Zarovnání na blokové ose (obvykle svisle). <br> Např. <code>align-items: end</code> zarovná položky ke spodní hraně kontejneru.</p>
  </div>

  <div role="article" class="reference-items-item">
    <h4><a href="https://github.com/machal/prirucka/blob/master/css-place-items.md">place-items</a></h4>
    <p><a href="https://github.com/machal/prirucka/blob/master/css-place-items.md"><img src="https://github.com/machal/prirucka/raw/master/./dist/images/small/vdlayout/css-place-items-schema.jpg" alt="Vlastnost place-items" /></a></p>
    <p>Zkratka pro zarovnání položek v obou směrech. <br> Např. <code>place-items: end center</code> zarovná položky ke spodní hraně a vodorovně na střed.</p>
  </div>

</div>

Ukázky kódu

Značku <code>, respektive její Markdown obdobu používáme jen výjimečně:

<code> nepoužíváme:

HTML značky lze opsat kapitálkami („Značka HTML slouží…“). JS a CSS kód prostě uvedeme bez <code> tak jak je. Vyplývá z toho samozřejmě, že je lepší se kódu na takovýchto místech vyhnout.

Kvůli e-bookům by bloková ukázka kódu měla mít maximální délku kódu kolem 60 znaků na řáku.

Zobrazení jen na webu nebo v e-boocích

Prostě odstavec s třídou .web-only. V ebooku bude při předzpracování textu odstraněno.

<div class="web-only" markdown="1">
Čtete referenční příručku vlastností, které je možné přiřadit položkám [flexboxu](css-flexbox.md).
</div>

Totéž jen pro e-booky pomocí .ebook-only:

<div class="ebook-only" markdown="1">
Čtete referenční příručku vlastností, které je možné přiřadit položkám [flexboxu](css-flexbox.md).
</div>

Pozor, není možné totéž udělat inline pomocí <span class="ebook-only" markdown="1">. Nějak to prostě nefunguje.

Speciální znaky

mPDF jako generátor PDF verze e-booků neumí fallback pro znaky, které nejsou ve fontech. Respektive, měl by umět, ale vrací to chyby.

V textech pro e-booky je tedy potřeba se vyhnout speciálním znakům jako je → nebo ⚡.

Umístění reklamy na webu

Standardně po druhém odstavci. Lze změnit jednou nebo více kotvami <!-- AdSnippet --> v obsahu.

Vkládání statistik CanIUse

Vložení obrázku nejlépe přes CanIUse Embed: caniuse.bitsofco.de.

Uvést ale adresu přímo z Cloudinary, přesměrování nemá rád náš lightbox:

<figure>
<img src="https://res.cloudinary.com/ireaderinokun/image/upload/v1/caniuse-embed/static/link-rel-preload-1590381119841.jpg" alt="Podpora preload v prohlížečích">
<figcaption markdown="1">
*Obrázek: Podpora přednačtení prohlížečích. Zdroj: [CanIUse Embed](https://caniuse.bitsofco.de/).*
</figcaption>
</figure>

Odkaz pak například touto formou:

Viz také [caniuse.com/css-containment](https://caniuse.com/#feat=css-containment)

Komponenty pro formátování v tisku nebo PDF

.pbi-avoid – zákaz zalamování uvnitř prvku (page-break-inside:avoid):

<div class="pbi-avoid" markdown="1">

<!-- Obsah, který se nesmí rozdělit na dvě stránky -->

</div>
<!-- .pbi-avoid -->

Autorství

Pokud není řečeno jinak, autorem všech textů Příručky je Martin Michálek: vrdl.cz/martin.

Externí autoři

Toto platí jak pro příručku, tak pro blog:

Ukázky: