s = "Python označevanje"
print(s)Python označevanje
V beležnicah Jupyter in v datotekah Quarto ne pišemo razlage neposredno kot oblikovano besedilo, temveč kot zapis v jeziku Markdown. To je preprost označevalni jezik, pri katerem z nekaj znaki določimo naslove, sezname, povezave, slike, preglednice in bloke kode.
Markdown je posebej uporaben zato, ker:
Jupyter, Quarto, GitHub in številnih drugih okoljih,Praktični cilj tega poglavja je, da bralec zna:
Markdown,JupyterLab, VS Code in Quarto.Več o Markdownu je na voljo na primer tukaj:
V nadaljevanju bomo pri vsakem sklopu najprej pokazali primer izvornega zapisa, nato pa še rezultat, ki ga tak zapis ustvari.
V JupyterLab ima vsaka celica svoj tip. Za razlago postopka uporabimo celico Markdown, za izvajanje ukazov pa celico Code.
Tipičen potek v JupyterLab je:
Code v Markdown,Shift+Enter, da se surovi zapis pretvori v oblikovano besedilo.V VS Code lahko na enak način urejamo:
.ipynb,.md,.qmd, ki jih uporablja Quarto.Ko želimo besedilo popraviti, se vedno vrnemo v način urejanja in spreminjamo izvorni zapis. Ta logika je povsod enaka, zato se znanje iz tega poglavja neposredno prenese tudi na druga poglavja knjige.
Pri delu v JupyterLab si je dobro zapomniti še nekaj praktičnih pravil:
Shift+Enter jo ponovno upodobimo,Tako beležnica ne postane le zaporedje ukazov, ampak razumljiv delovni dokument.
Naslove najpogosteje pišemo z znakom #. Število znakov določa raven naslova.
Izvorni zapis:
# Naslov 1
## Naslov 2
### Naslov 3
#### Naslov 4
##### Naslov 5
###### Naslov 6Pomen posameznih vrstic:
# Naslov 1 ustvari naslov prve ravni,## Naslov 2 ustvari naslov druge ravni,### Naslov 3 ustvari naslov tretje ravni,#### Naslov 4 ustvari naslov četrte ravni,##### Naslov 5 ustvari naslov pete ravni,###### Naslov 6 ustvari naslov šeste ravni.Naslov 1 in naslov 2 lahko dosežemo tudi s podčrtavanjem. Tak zapis danes srečamo redkeje, vendar ga je dobro poznati.
Izvorni zapis:
Alt-Naslov 1
============
Alt-Naslov 2
------------Pomen:
= ustvari naslov prve ravni,- ustvari naslov druge ravni.Pri delu v daljših beležnicah in poglavjih je priporočljivo uporabljati dosledno hierarhijo naslovov, saj tako dobimo preglednejšo strukturo dokumenta.
Zelo pogosta uporaba Markdowna je poudarjanje posameznih delov besedila.
Izvorni zapis:
Poudarek oziroma ležeče besedilo dosežemo z *zvezdicami* ali _podčrtaji_.
Močan poudarek ali krepko dobimo z **dvojnimi zvezdicami**
ali __dvojnimi podčrtaji__.
Oboje lahko tudi kombiniramo z **zvezdicami in _podčrtaji_**.
Za prečrtavanje uporabljamo tildo. ~~Takole.~~Rezultat:
Poudarek oziroma ležeče besedilo dosežemo z zvezdicami ali podčrtaji.
Močan poudarek ali krepko dobimo z dvojnimi zvezdicami ali dvojnimi podčrtaji.
Oboje lahko tudi kombiniramo z zvezdicami in podčrtaji.
Za prečrtavanje uporabljamo tildo. Takole.
V učbeniških besedilih je priporočljivo, da poudarek uporabljamo zmerno. Dobro služi za označevanje pomembnih pojmov, opozoril ali delov ukazov, ne pa za vizualno okrasje.
Markdown zelo dobro podpira oštevilčene in neoštevilčene sezname. Ti so posebej uporabni pri navodilih po korakih, razlagi postopkov in krajših povzetkih.
Izvorni zapis:
1. Oštevilčen seznam
2. Še ena možnost
* Podmožnost
1. Prave številke so nepomembne. Samo da je številka.
1. Urejena podskupina
4. Še ena možnost.Rezultat:
Pri seznamih so odstavki pravilno poravnani, če uporabljamo prazne vrstice in primerne zamike. To je posebej pomembno, ko v posamezno točko vključimo daljše pojasnilo.
Izvorni zapis:
Za prelom vrstice znotraj odstavka je potrebno uporabiti dva
končna presledka.
Tole je nova vrstica, ki pa je v istem odstavku.
(To je v nasprotju z nekaterimi drugimi prikazovalniki, kjer to ni vedno nujno.)Praktični rezultat v Markdownu navadno dosežemo takole:
Za prelom vrstice znotraj odstavka je potrebno uporabiti dva končna presledka.
Tole je nova vrstica, ki pa je v istem odstavku.
(To je v nasprotju z nekaterimi prikazovalniki, kjer to ni vedno nujno.)
Neoštevilčene sezname lahko pišemo na več načinov.
Izvorni zapis:
* Neoštevilčeni seznami imajo lahko zvezdico
- ali minus
+ ali plusRezultat:
Za preglednost je najbolje, da znotraj istega dokumenta izberemo en slog in se ga držimo dosledno.
Povezave lahko ustvarimo na več načinov. Najpogosteje uporabljamo neposredne povezave z besedilom in URL naslovom, včasih pa tudi referenčne oblike.
Izvorni zapis:
[To je povezava](https://www.google.com)
[To je povezava z naslovom](https://www.google.com "Google's Homepage")
[To je referenca][referenca kar tako]
[Referenca na datoteko.](../blob/master/LICENSE)
[Reference so lahko označene s številkami][1]
Ali pa samo označimo [link besedilo].
URLji in URLji v oglatih oklepajih se samodejno pretvorijo v povezave.
http://www.example.com ali <http://www.example.com> in včasih tudi
www.example.com.
[referenca kar tako]: https://www.mozilla.org
[1]: http://slashdot.org
[link besedilo]: http://www.reddit.comRezultat:
Reference so lahko označene s številkami
Ali pa samo označimo link besedilo.
URLji in URLji v oglatih oklepajih se samodejno pretvorijo v povezave: http://www.example.com ali http://www.example.com in včasih tudi www.example.com.
V praksi se pri učbenikih in poročilih največkrat najbolje obnese neposredna oblika [besedilo](povezava), referenčne oblike pa so uporabne pri daljših dokumentih z več ponovitvami.
Slike vključimo podobno kot povezave, le da pred oglatim oklepajem dodamo klicaj.
Izvorni zapis:
Rezultat:

Besedilo v oglatem oklepaju je nadomestni opis slike. Ta je uporaben za dostopnost in za primere, ko se slika ne naloži pravilno.
Markdown zelo pogosto uporabljamo prav zato, ker omogoča lep prikaz programske kode skupaj z razlago.
Bloki s programsko kodo so del Markdowna, označevanje sintakse pa je odvisno od prikazovalnika. Okolja, kot so GitHub, Jupyter in Quarto, običajno podpirajo označevanje za številne jezike.
Koda v besedilu je označena z enojnimi ostrivci.
Izvorni zapis:
Koda v besedilu je označena kot `koda` in jo označujeta ostrivca na obeh straneh.Rezultat:
Koda v besedilu je označena kot koda in jo označujeta ostrivca na obeh straneh.
Za večvrstično kodo uporabljamo ograjene bloke.
Izvorni zapis:
```javascript
var s = "JavaScript označevanje";
alert(s)
```Rezultat:
var s = "JavaScript označevanje";
alert(s);Izvorni zapis:
::: {#29e7909c .cell execution_count=1}
``` {.python .cell-code}
s = "Python označevanje"
print(s)
```
::: {.cell-output .cell-output-stdout}
```
Python označevanje
```
:::
:::
Rezultat:
s = "Python označevanje"
print(s)Python označevanje
Če oznake jezika ne navedemo, se koda sicer še vedno prikaže, vendar navadno brez posebnega barvanja sintakse.
Izvorni zapis:
```
Ni oznake jezika, zato ni označevanja.
Lahko pa napišemo kako <b>oznako</b>.
```Rezultat:
Ni oznake jezika, zato ni označevanja.
Lahko pa napišemo kako <b>oznako</b>.
V učbeniškem besedilu je priporočljivo, da je pri blokih kode jezik naveden skoraj vedno, saj je koda tako precej preglednejša.
Preglednice niso del najosnovnejše specifikacije Markdowna, podpirajo pa jih skoraj vsi sodobni prikazovalniki.
Z dvopičji lahko označimo poravnavo stolpcev.
Izvorni zapis:
| Preglednice | So | Super |
|:-------------|:--------------:|-------:|
| stolpec 3 je | poravnan desno | 1600 € |
| stolpec 2 je | usredinjen | 12 € |
| črte | so uporabne | 5 € |Rezultat:
| Preglednice | So | Super |
|---|---|---|
| stolpec 3 je | poravnan desno | 1600 € |
| stolpec 2 je | usredinjen | 12 € |
| črte | so uporabne | 5 € |
Glavo preglednice označujejo vsaj trije pomišljaji. Navpičnice niso povsem obvezne, a navadno izboljšajo preglednost izvornega zapisa.
Izvorni zapis:
Manj | pregleden | zapis
--- | --- | ---
*prav tako* | `ustvari` | **preglednico**
1 | 2 | 3Rezultat:
| Manj | pregleden | zapis |
|---|---|---|
| prav tako | ustvari |
preglednico |
| 1 | 2 | 3 |
Pri večjih tabelah je včasih smiselno razmisliti tudi o Quarto ali HTML rešitvah, a za krajše preglednice je ta zapis zelo priročen.
Citati oziroma navedki se začnejo z znakom >. Primerni so za poudarjene misli, navodila ali kratke povzetke.
Izvorni zapis:
> Citati so primerni za navajanje in jih še najbolj poznamo iz e-pošte.
> To je del istega navedka.Rezultat:
Citati so primerni za navajanje in jih še najbolj poznamo iz e-pošte. To je del istega navedka.
Besedilo, ki ni označeno z >, se vrne v navaden odstavek.
Tole pa ni navedek.
Izvorni zapis:
> Tole je zelo dolga vrstica, ki pa se bo še vedno pravilno izpisala kot
navedek. Kljub prelomu. Še malo, da bo res dolgo in pravilno izpisano na
vseh širinah zaslonov. In ja, lahko uporabimo *dodatno* **oblikovanje**.Rezultat:
Tole je zelo dolga vrstica, ki pa se bo še vedno pravilno izpisala kot navedek. Kljub prelomu. Še malo, da bo res dolgo in pravilno izpisano na vseh širinah zaslonov. In ja, lahko uporabimo dodatno oblikovanje.
Markdown lahko po potrebi dopolnimo tudi z ukazi HTML. To je uporabno takrat, ko želimo nekaj, česar čisti Markdown ne podpira dovolj dobro.
Izvorni zapis:
<dl>
<dt>Definicija</dt>
<dd>Včasih se uporablja.</dd>
<dt>Markdown in HTML</dt>
<dd>Tole pa *ne* deluje **dobro**. Uporabiti je treba HTML
<em>oznake</em>.</dd>
</dl>Rezultat:
Pomembno je opaziti, da znotraj nekaterih HTML struktur običajno ne moremo pričakovati, da bo Markdown oblikovanje delovalo povsem enako kot zunaj njih. Zato je v takih primerih praviloma bolje dosledno uporabljati HTML oznake.
Vodoravne črte ustvarimo s tremi ali več pomišljaji, zvezdicami ali podčrtaji.
Izvorni zapis:
---
***
___Rezultat:
Tak element je uporaben za ločevanje večjih vsebinskih sklopov, vendar ga ni dobro uporabljati prepogosto.
Pri Markdownu je dobro razumeti razliko med novo vrstico in novim odstavkom. Najboljši način učenja je pogosto prav preizkušanje različnih zapisov.
Izvorni zapis:
Prva vrstica tako za začetek.
Tale vrstica je od prejšnje ločena z dvema znakoma za novo vrstico in
bo zato prikazana kot poseben odstavek.
Tole je tudi poseben odstavek, ampak ...
Tale vrstica je ločena samo z enim znakom za novo vrstico in je zato
v istem odstavku. Če pa na koncu vrstice vstavimo dva presledka,
kot je tule ...
Potem pa je nadaljevanje nova vrstica v istem odstavku.Rezultat:
Prva vrstica tako za začetek.
Tale vrstica je od prejšnje ločena z dvema znakoma za novo vrstico in bo zato prikazana kot poseben odstavek.
Tole je tudi poseben odstavek, ampak … Tale vrstica je ločena samo z enim znakom za novo vrstico in je zato v istem odstavku. Če pa na koncu vrstice vstavimo dva presledka, kot je tule …
Potem pa je nadaljevanje nova vrstica v istem odstavku.
V praksi si velja zapomniti:
V Markdown celicah v Jupyter in Quarto lahko pišemo tudi matematične izraze s sintakso, ki temelji na LaTeX.
Za izraz znotraj vrstice uporabimo enojne dolarje:
Pitagorov izrek zapišemo kot $a^2 + b^2 = c^2$.Rezultat:
Pitagorov izrek zapišemo kot \(a^2 + b^2 = c^2\).
Za samostojen izraz v svoji vrstici uporabimo dvojne dolarje:
$$
\binom{n}{k} = \frac{n!}{k!(n-k)!}
$$Rezultat:
\[ \binom{n}{k} = \frac{n!}{k!(n-k)!} \]
Nekaj pogostih primerov:
$\frac{\alpha^2}{\beta}$
$$
a_0+\frac{1}{a_1+\frac{1}{a_2+\frac{1}{a_3+\cdots}}}
$$
$$
f(x) = e^{-x}
$$Rezultat:
\(\frac{\alpha^2}{\beta}\)
\[ a_0+\frac{1}{a_1+\frac{1}{a_2+\frac{1}{a_3+\cdots}}} \]
\[ f(x) = e^{-x} \]
To je posebej uporabno pri statistiki, linearní algebri, optimizaciji in drugih temah, kjer želimo ob kodi zapisati tudi matematično ozadje.
Videov v osnovnem Markdownu navadno ne vstavljamo neposredno, lahko pa vstavimo sliko s povezavo na video. To je preprost in zelo razširjen pristop.
Izvorni zapis:
[](http://www.youtube.com/watch?v=VIDEO_ID)Rezultat:
Pri tem je VIDEO_ID oznaka videa. V zgornjem primeru je to GEmuEWjHr5c.
Ko Markdown uporabljamo v beležnicah, vajah in poglavjih knjige, se dobro obnese nekaj preprostih pravil:
Tak zapis je precej preglednejši kot dolge neprekinjene razlage, hkrati pa omogoča, da beležnica ostane uporabna tudi pozneje, ko jo odpremo znova ali delimo z drugimi.
Quarto uporablja Markdown kot osnovni jezik za pisanje poglavij, navodil in poročil. Zato je znanje iz tega poglavja neposredno uporabno tudi pri urejanju te knjige:
.qmd,To je eden od glavnih razlogov, da je Markdown smiseln že zelo zgodaj v knjigi: isti pristop bomo uporabljali skoraj povsod naprej.