Staattiset sivugeneraattorit ovat varsin suosittuja ja käytännöllisiä työkaluja tietynlaisten sivustojen rakentelemiseen. Esittelen tässä, miten tähän ryhmään kuuluva työkalu MkDocs toimii.
Staattinen sivugeneraattori?
Staattinen sivugeneraattori tarkoittaa ohjelmistoa, joka luo (generoi) käyttäjän tietosisällöistä staattisen sivuston. Tämä tarkoittaa siis ihan perinteistä nettisivustoa, joka koostuu HTML-sivuista.
Vastakohtana dynaaminen sivusto on sellainen, jonka sisältö luodaan (teoriassa) jokaisella sivunlatauksella erikseen tietokannasta olevasta aineistosta ja sivupohjista.
Staattisilla sivustoilla saavutetaan tiettyjä etuja:
- Palvelimia kohtaan ei ole juurikaan vaatimuksia ja sivusto toimii salamannopeasti lähes missä tahansa. Isompi dynaaminen sivusto vaatii kalliimman ja laadukkaamman palvelinympäristön toimiakseen hyvin.
- Staattinen sivusto ei tarjoa hakkereille minkäänlaista tarttumapintaa. Jos palvelin vain on turvallinen, sivustolla ei yksinkertaisesti ole mitään hakkeroitavaa.
- Tietokantapalvelimia ei tarvita, eikä ohjelmistojen versiopäivityksistä tarvitse murehtia.
- Kun koko sivusto on yksinkertaisia, millä tahansa ohjelmalla luettavia tekstitiedostoja tietokoneella, sivuston saa näppärästi versionhallinnan piiriin.
- Yksinkertaiset HTML-tiedostot kestävät ongelmitta suuriakin määriä liikennettä.
Dynaamisilla sivuilla on toki puolensa:
- Sivuston sisällön muokkaaminen on yleensä helpompaa dynaamisilla sivuistoilla, joissa on näppärä käyttöliittymä.
- Joitain toiminnallisuuksia on helpompaa toteuttaa dynaamisella sivustolla. Tällaisia ovat esimerkiksi haku, kommentointi, palautelomakkeet ja niin edelleen.
- Dynaamisella sivustolla on mahdollista tehdä kirjautumisia ja esimerkiksi erilaisten käyttäjien erilaisia oikeuksia edellyttävää toiminnallisuutta.
Tämä on monipuolinen maailma, jossa on paljon erilaisia työkaluja. Suosittuja ovat esimerkiksi Hugo, Jekyll ja Gatsby. Näiden työkalujen tehokas käyttö edellyttää jonkun verran ohjelmointiosaamista.
MkDocs – dokumentaatiotyökalu
MkDocs on yksinkertainen sivugeneraattori, joka on erityisesti tarkoitettu erilaisten dokumentaatioiden luomiseen. Sillä ei kannata alkaa rakentamaan esimerkiksi blogia, mutta erilaisten staattisten tekstikokoelmien tuottamisessa se on oikein näppärä työkalu.
Esimerkiksi projektidokumentaatiot, kirjat ja kurssit taipuvat MkDocsilla helppokäyttöisiksi ja selkeiksi sivustoiksi helposti. Yksinkertaiset kotisivutkin voi tehdä MkDocsilla – MkDocsin omat sivut on luonnollisesti tehty sillä.
MkDocs perustuu Markdown-dokumentteihin. Markdown on yksinkertainen tapa lisätä muotoiluja tekstitiedostoihin. Sivuston rakenne määritellään sijoittamalla tiedostot alihakemistoihin. Lisäksi tarvitaan vain yksinkertainen asetustiedosto ja teema, ja MkDocs tuottaa nopeasti ja tehokkaasti sivuston lähdemateriaalin pohjalta.
Olen itse joskus rakennellut MkDocsilla esimerkiksi pientä peliohjelmointikurssia. Projekti jäi kesken ja todennäköisesti keskeneräisenä pysyykin, mutta se on kelpo esimerkki projektista, joka sopii erinomaisesti MkDocsilla tehtäväksi.
Asennus
MkDocsin voi asentaa pakettimanagerilla, mutta ainakin Mac OS:lla olen törmännyt pieniin vaikeuksiin Homebrew’llä asennetun MkDocsin kanssa. Paremmin toimii Python-asennus:
python -m pip install mkdocs
Jos et ole vielä asentanut pipiä eli Pythonin paketinhallintaa, tee se ensin eli hae get-pip.py ja suorita se:
python get-pip.py
Uuden projektin luominen
Uusi projekti luodaan komennolla
mkdocs new oma-projekti
Tämä luo hakemiston oma-projekti ja sinne minimimäärän projektiin vaadittavia tiedostoja, eli mkdocs.yml-dokumentaatiotiedoston ja docs-hakemiston, jonne tulevat projektiin sisältyvät dokumentit.
Sen jälkeen voi antaa komennon
mkdocs serve
Tämä käynnistää MkDocsin palvelimen, joka näyttää, miltä sivusto valmiina näyttää. Kun palvelin on käynnissä, selaimella voi mennä osoitteeseen http://localhost:8080/ katsomaan valmista projektia.
Asetuksien kanssa säätämistä ei juurikaan tarvita. Esimerkiksi mainitun peliohjelmointikurssin projektin asetustiedosto näyttää tältä:
site_name: Pelintekoa Phaserilla nav: - Etusivu: index.md - Kurssi: - Perustukset: kurssi/perustukset.md - "Hello World": kurssi/helloworld.md - "Suunnittelupalaveri": kurssi/suunnittelupalaveri.md - "Phaserin perusasetukset": kurssi/phaser-perusasetukset.md - "Alussa on sana": kurssi/sana-spriteksi.md - "Syötteiden lukemista": kurssi/syote.md - "Reagoidaan äänellä": kurssi/aanta-ja-vimmaa.md theme: name: 'material' language: 'fi'
Asetustiedostossa määritellään sivuston nimi, käytetty teema ja sivuston kieli, ja loput on sivuston päätason navigoinnin rakennetta.
Ulkoasuvaihtoehtoja on tarjolla jonkun verran teemojen muodossa. Lisäominaisuuksia kaipaaville tarjolla on lisäosia, joilla MkDocsiin saa lisätoiminnallisuutta.
Valmiin sivuston julkaiseminen
Kun sisältöä on luotu tarpeeksi, voidaan komentaa
mkdocs build
Nyt MkDocs rakentaa sivuston tiedostoiksi. Hakemistosta site löytyvät paketti on valmis julkaistavaksi. Sivusto julkaistaa yksinkertaisesti siirtämällä tämän hakemiston sisältö johonkin julkisesti saatavilla olevaan paikkaan.
Julkaisu on helppo automatisoida sopivilla työkaluilla. Esimerkiksi pitämällä sivusto GitHubissa versionhallinnassa, se voidaan sieltä virittää julkaistavaksi vaikkapa Netlifyssä.
Prosessin saa automatisoitua niin, että Netlify nuuskii muutoksia GitHubissa. Kun sivuston sisältöä muokkaa omalla koneella ja lähettää muutokset GitHubiin, Netlify huomaa ne, ajaa halutun build-komennon (mkdocs build) ja laittaa sitten site-hakemiston sisällön julkiseksi.
Tällä tavalla perustettua sivustoa on mahdollista ylläpitää vaivattomasti ja sisällöstä voi helposti olla vastuussa useampikin henkilö. Versionhallinta varmistaa, että kukaan ei jyrää toisten tekemiä muutoksia ja että kaikki aikaisemmat versiot pysyvät tallessa.