Markdown on kevyt merkintäkieli, jolla tavalliseen tekstiin lisätään rakennetta ja muotoiluja yksinkertaisten merkkien avulla. Esimerkiksi otsikko merkitään risuaidalla (#) ja lihavointi kahdella tähdellä (**). Teksti säilyy luettavana myös ilman muotoilua, ja Markdownia tukeva ohjelma voi näyttää sen muotoiltuna dokumenttina.
Markdown-tiedoston pääte on yleensä .md. Tiedostoa voi kirjoittaa tavallisella tekstieditorilla tai esimerkiksi Visual Studio Codella, jossa lopputulosta voi tarkastella Markdown-esikatselussa.
Tässä oppaassa käsitellään Markdownia, koska ohjelmistoprojektien dokumentit laaditaan nykyään usein sillä. Markdownilla voidaan kirjoittaa esimerkiksi projektin esittely (README.md), asennusohjeet, vaatimusmäärittely ja tekninen dokumentaatio. Dokumentit voidaan säilyttää samassa Git-versionhallinnassa kuin lähdekoodi, jolloin niiden muutoksia voidaan seurata ja katselmoida yhdessä koodimuutosten kanssa. Esimerkiksi GitHub näyttää Markdown-tiedostot valmiiksi muotoiltuina.
Seuraavissa esimerkeissä harmaa laatikko näyttää, mitä Markdown-tiedostoon kirjoitetaan. Aloita dokumentin rakenteesta ja lisää sen jälkeen tarvittavat muotoilut.
Otsikko aloitetaan yhdellä tai useammalla #-merkillä ja välilyönnillä. Merkkien määrä määrittää otsikkotason: # on pääotsikko, ## alaotsikko ja ### sitä alempi otsikko. Otsikkotasoja on kuusi.
# Oppilasrekisteri
## Asennus
### Tietokannan valmisteluValitse otsikkotasot sisällön hierarkian mukaan. Dokumentissa on yleensä yksi pääotsikko. Jätä otsikon ympärille tyhjät rivit, jotta rakenne on selkeä.
Tavallinen teksti kirjoitetaan sellaisenaan. Uusi kappale erotetaan edellisestä tyhjällä rivillä. Pelkkä rivinvaihto ei yleensä aloita uutta kappaletta tai tee näkyvää rivinvaihtoa muotoillussa dokumentissa.
Oppilasrekisteri sisältää opiskelijoiden perustiedot.
Tietoja ylläpitää opintosihteeri.
Opiskelija voi tarkastella omia tietojaan.Esimerkistä muodostuu kaksi kappaletta: kaksi ensimmäistä riviä kuuluvat samaan kappaleeseen ja viimeinen rivi omaansa.
Ympäröi korostettava teksti kahdella tähdellä molemmilta puolilta. Älä jätä välilyöntiä tähtien ja korostettavan tekstin väliin.
Tallenna muutokset ennen **uloskirjautumista**.Muotoiltuna: Tallenna muutokset ennen uloskirjautumista.
Numeroimaton lista tehdään aloittamalla jokainen kohta yhdysmerkillä ja välilyönnillä. Se sopii asioihin, joiden järjestyksellä ei ole merkitystä.
Järjestelmän käyttäjäryhmät:
- Opiskelija
- Opettaja
- OpintosihteeriNumeroitu lista tehdään numerolla, pisteellä ja välilyönnillä. Käytä sitä esimerkiksi työvaiheisiin, jotka tehdään tietyssä järjestyksessä.
Asennuksen vaiheet:
1. Lataa projektin tiedostot.
2. Luo tietokanta.
3. Käynnistä sovellus.Kirjoita jokainen listakohta omalle rivilleen ja jätä listan ympärille tyhjä rivi.
Linkin näkyvä teksti kirjoitetaan hakasulkeisiin ja osoite heti niiden perään sulkeisiin: [linkin teksti](osoite).
Projektin lähdekoodi on palvelussa [GitHub](https://github.com).
Katso myös [asennusohje](docs/asennus.md).Ensimmäinen linkki johtaa verkkosivulle. Toinen on suhteellinen linkki: se viittaa nykyisen dokumentin sijainnista alkaen docs-kansion tiedostoon asennus.md. Linkin tekstin kannattaa kertoa, mitä linkin takaa löytyy.
Taulukon sarakkeet erotetaan pystyviivoilla (|). Ensimmäisellä rivillä ovat sarakeotsikot ja toisella erotinrivi, jossa jokaiseen sarakkeeseen kirjoitetaan vähintään kolme yhdysmerkkiä (---). Sen jälkeen tulevat tietorivit.
| Dokumentti | Tarkoitus |
| --- | --- |
| README.md | Projektin esittely |
| asennus.md | Asennusohjeet |Muotoiltuna taulukko näyttää tältä:
| Dokumentti | Tarkoitus |
|---|---|
| README.md | Projektin esittely |
| asennus.md | Asennusohjeet |
Jätä taulukon ympärille tyhjä rivi. Sarakkeita ei tarvitse kohdistaa välilyönneillä, mutta jokaisessa rivissä kannattaa olla sama määrä sarakkeita.
Taulukot eivät kuulu alkuperäiseen Markdownin perussyntaksiin, mutta niitä tukee esimerkiksi GitHub Flavored Markdown (GFM). Tarkista käyttämäsi ohjelman esikatselusta, että taulukko ja muut muotoilut näkyvät oikein.