Hyppää sisältöön

2: Markdown

Tip

Jos Markdown-kielen syntaksi ja Material for MkDocs -teema ovat sinulle entuudestaan tuttua kauraa, voit siirtyä seuraavaan lukuun.

Opiskele perusteet

Markdown-koodiin tutustumiseen on monta tapaa. Suosittelen tapaa, jossa käytät tätä juuri nyt lukemaasi sivustoa apuna. Tämän koodi löytyy gh:sourander/oat -repositoriosta. Toimi alla olevien vaiheiden mukaisesti:

1⃣ Basic Syntax

Käy lukemassa Markdown Guide: Basic Syntax.

  • Silmäile juuri tämän dokumentin lähdekoodia.
  • Etsi koodista Basic Syntax -linkin mukaisia elementtejä (otsikot, kappaleet, listat, lihavointi)
  • Aloita oppimispäiväkirjasi ja käytä näitä perusmuotoiluita.

2⃣ Extended Syntax

Käy lukemassa Markdown Guide: Extended Syntax.

  • Etsi Oppimispäiväkirja 101:sta esimerkkejä Extended Syntax -elementeistä.
  • Käytä niitä myös oppimispäiväkirjassasi.

3⃣ Material for MkDocs

Tämä sivusto käyttää Material for MkDocs -teemaa (MkDocs:n päällä). Tutustu Material for MkDocs: References-dokumentaatioon. Selvitä, mitä ainakin seuraavat ovat, ja kuinka niitä käytetään:

  • admonitions
  • code blocks
  • footnotes

Etsi Oppimispäiväkirja 101:sta esimerkkejä näistä elementeistä. Käytä niitä myös oppimispäiväkirjassasi.

🔁 Testaa selaimella

Kun kirjoitat oppimispäiväkirjaa, aja Material for MkDocs -sivustoa lokaalisti. Tarkista, että sivusto renderöityy siten, kuten sen haluat renderöityvän. Jos ei, selvitä, mikä syntaksissa on pielessä: yleensä vika löytyy joko sisennyksestä tai puuttuvasta rivinvaihdosta. Palaa tarpeen mukaan aiemmin mainittujen ohjeiden pariin.

Muotoiluvinkkejä

Voit käyttää kaikkia niitä Markdown-kielen ominaisuuksia, joita Material for MkDocs tukee, ja jotka sinä olet sivustolle aktivoinut 1 mkdocs.yml -tiedostossa. Yksi näistä ominaisuuksista on Footnote, joka mahdollistaa Vancouver-tyyliset lähdemerkinnät. Opiskelijoiden cookiecutter-templaatissa on vakiona aktivoituna tämä ominaisuus: katso tiedoston mkdocs.yml sisältö. Markdown-alaviitteitä tukee myös esimerkiksi Gitlab (GitLab Flavoured Markdown, GLFM) 2, kuten monet muutkin alustat ja sovellukset, jotka ymmärtävät Extended Markdownia 3. Huomaa, että oppimispäiväkirjan rakenne on yksi arvosteluperusteista. Tee se huolella.

Otsikot

Material for MkDocs -sivuston Table of Contents -osio on hyvä apuväline otsikoiden hierarkisuuden tarkkailuun. Käytä otsikoita järkevästi. Liiallinen otsikointi hankaloittaa lukemista, mutta liian vähäinen otsikointi tekee tekstistä raskasta. Tasapaino on avain, ja tulevana asiantuntijana sinun tehtäväsi on etsiä tätä tasapainoa. Table of Contents löytyy tämän ikkunan oikeasta yläkulmasta. Löydät sen tuolta suunnasta ↗

Luetelmat

Käytä luetelmaa kun listaat asioita 4.

  • Tämä
  • On
  • Luettelo

Ethän kirjoita kirjoita koko merkintää listamuodossa; korkeakouluopiskelijan tulee osata kirjoittaa kokonaisin lausein. Esimerkiksi pizzanteon vaiheet pääpiirteittäin ovat selkeä luettelo, mutta yksityiskohtaisten pizzanvalmistuksen vaiheiden listaaminen on jo liikaa.

Koodilohkot

Käytä koodilohkoja, kun kirjoitat koodia.

# Tämä on koodilohko
print("Olen koodilohko!")

Koodilohko luodaan asettamalla koodi kolmen backtickin (tai joskus harvoin kolmen tilden sisään.) Backtick luodaan painamalla Shift+` näppäimiä, joista jälkimmäinen löytyy tyypillisesti Backspace -näppäimen eli askelpalauttimen vasemmalta puolelta. Koodilohkon aloittavan blokin perään tulee kirjoitettaa käytetyn koodin kieli, jotta syntaksin värikorostuvat toimivat oikein.

🖼 Kuvat

![Kuvaus kuvasta](../images/kuvan_nimi.png)

Voit käyttää valokuvia tai kuvakaappauksia oppimispäiväkirjassasi. On suositeltavaa pienentää kuvia ennen niiden lataamista GitLabiin, mikäli kuvat ovat useita tuhansia pikseleitä kooltaan. Kuvan lisääminen hoituu yllä olevan koodisnippetin mukaisesti. Huomaa, että polku on relatiivinen.

📈 Kuvaajat

Kuvio 1: Kuvitteellinen jäljellä olevan ja syödyn pizzan suhdetta kuvastava piirakkakuvaaja. Kuville ja kuvaajille on hyvä lisätä kuvateksti. Tämä tässä toimii esimerkkinä.

Todella yksinkertaisiin kuvaajiin voit käyttää mermaidia. Mermaid on helppo ja nopea tapa luoda yksinkertaisia kuvaajia 5. Kyseisellä kielellä on tehty yllä näkyvä piirakkakuvaaja.

Monimutkaisempiin kuvaajiin voit käyttää PNG- tai SVG-kuvia. Käytä kuvia harkiten. Noudata tekijänoikeuksia ja käytä kuvia, jotka ovat vapaasti käytettävissäsi. Käytä kuvien luomiseen haluamasi ohjelmia tai web-sovelluksia. Yksi suositeltu web-sovellus on excalidraw.

Lähdeluettelo

  1. Material for MkDocs. Reference. https://squidfunk.github.io/mkdocs-material/reference/ ↩

  2. GitLab Docs. GitLab Flavored Markdown (GLFM). https://docs.gitlab.com/ee/user/markdown.html ↩

  3. Markdown Guide. Extended Syntax. https://www.markdownguide.org/extended-syntax/ ↩

  4. Kielitoimiston ohjepankki. Luetelma. https://kielitoimistonohjepankki.fi/ohje/luetelma/ ↩

  5. Mermaid. Pie chart diagrams. https://mermaid.js.org/syntax/pie.html ↩