| published |
|---|
- Wijzig alleen
.md-bestanden. - Blijf dus af van de volgende mappen en bestanden:,
/.git/,/system/,/*.html,/*.js,/*.liquid,/*.puml,/*.xml,/*.yml - Vul bij
date:de datum van publiceren in de branchmasterin (of vandaag), behalve:- als alleen de front matter is gewijzigd (datum niet aanpassen);
- als de wijziging uitsluitend redactioneel is (datum niet aanpassen);
- als het gaat om een publicatie met een officiële datum, bijvoorbeeld als het in de map
/_beleidskaders/staat (gebruik de officiële datum).
- Vul in de front matter alleen metagegevens in die bestaan in de betreffende map, bijvoorbeeld het trefwoord is de unieke
title:in de front matter van een bestand in de map_trefwoorden. - De waarde van de
title:moet uniek zijn binnen de map. - De naam van het bestand moet gelijk zijn aan de slug van de
title:(komt ongeveer neer op alle leestekens verwijderen en de spaties vervangen door een streepje-), gevolgd door.md(behalve in de map/_beslisboomvragen/).
De website staat in de repository https://github.com/imbag/praktijkhandleiding/tree/master/docs en wordt gepubliceerd op imbag.github.io/praktijkhandleiding. Als de naam van de repository wijzigt, wijzigt de naam van de website mee. Alternatief kan dat ook onder een eigen URL, zie https://help.github.com/articles/using-a-custom-domain-with-github-pages.
De website is gebouwd op Github Pages en geprogrammeerd in Jekyll, Liquid, HTML, JavaScript, CSS, kramdown en Mermaid. De vormgeving is afgeleid van de sjabloon Ed. en de snippet CSS Tags. Voor beide geldt de MIT-licentie: zie hier voor Ed. en hier voor CSS Tags.
De laatste release van Mermaid vind je hier.
Analoog aan de licentie die het ministerie heeft gekozen voor de inhoud van de Catalogus BAG, is de zelf geschreven code van de website onderworpen aan een Creative Commons-licentie, namelijk Creative Commons Naamsvermelding-NietCommercieel-GelijkDelen 4.0 Internationaal. Hiervan is nog geen Nederlandse versie beschikbaar.
Alle teksten moeten worden geschreven in de Markdown-variant kramdown. Dit is een eenvoudig te leren en toekomstbestendig tekstformaat dat lijkt op platte tekst en niet gebonden is aan welk specifiek softwarepakket dan ook en de aandacht heeft van W3C.
Het is mogelijk om eenvoudige diagrammen zoals stroomschema's in te voegen volgens de Mermaid-specificatie. Mermaid kent op dit moment veel minder gebruikers dan Markdown, maar volgt dezelfde aanpak, zoals vrij te gebruiken, open bron, opslaan als platte tekst, scheiden van inhoud en opmaak en eenvoudig door mensen te schrijven en te lezen zonder speciale software.
De manier waarop Jekyll, Markdown en Mermaid informatie structureren en verbinden, is in beginsel machine-leesbaar.
Verouderde browsers (zoals Internet Explorer) kunnen afbeeldingen in het Scalable Vector Graphics-formaat (.svg) niet goed weergegeven, maar voor moderne browsers biedt dit formaat juist aantrekkelijke voordelen. Zo blijven deze afbeeldingen scherp als je heel ver inzoomt of ze heel groot afdrukt en kan de browser tijdens het laden van de webpagina zelf een tekstuele beschrijving van een diagram omzetten naar een plaatje, zoals dat bij de Mermaid-diagrammen gebeurt.
De inhoud van de repository op GitHub is niet de website die online staat, maar wordt door GitHub Pages gebruikt om een website te genereren. Zodra je met behulp van een commit (al dan niet via een pull request) de inhoud van de branch master wijzigt, wordt automatisch een nieuwe versie van de website gegenereerd. Dit kan enkele minuten duren.
Bij het genereren van de website kan de generator uit verschillende soorten pagina's kiezen. Dit wordt bepaald door de waarde van layout: in de front matter. In beginsel kies je hiervoor dezelfde waarde als die van andere bestanden in dezelfde map.
Doordat de branch master de bron vormt voor deze website, kunnen momentopnamen van de website worden bewaard als release. GitHub biedt ook aan om de website te genereren vanuit de map /docs/, maar dat is vooral zinvol als de website een bijproduct is, zoals bij de Catalogus BAG. Eenzelfde redenering geldt voor een website die wordt gegenereerd vanuit de branch gh-pages. Bovendien lijkt dat lastiger te beheren.
Het rubriek teksten komt als zodanig niet voor op de website, maar wordt in deze handleiding gebruikt om de werking van de website te illustreren en representeert rubrieken als objecttypen, attributen, en dergelijke.
404.html: de webpagina die wordt getoond als iemand een verkeerde URL intypt, zoals imbag.github.io/praktijkhandleiding/verkeerd.html._config.yml: diverse besturingsparameters voor het genereren van de website.atom.xml: hiermee moet het mogelijk zijn om een atom-feed in te richten voor de website (nog niet uitgeprobeerd).index.html: de startpagina van de website.teksten.html: de startpagina voor het thema teksten (let op het meervoud van de naam).zoek.html: zoeken met JavaScript.
Hierin staan alleen bestanden die niet op de website komen.
In deze map staan alle afbeeldingen die worden aangeroepen vanuit de teksten in /_snippets/. Dit betreft alleen de teksten met een meervoudsnaam, zoals teksten-boven.md. Afbeeldingen die worden aangeroepen vanuit snippets met een enkelvoudsnaam, zoals tekst-artikelintro.md, moeten waarschijnlijk staan in /_layouts/afbeeldingen/ (maar dat komt nog niet voor).
afbeeldingen/
In deze map staan de artikelen met de eigenlijke inhoud van de website.
Bestanden die nodig zijn voor het raamwerk van de website.
De stylesheet waarmee de websitegenerator begint bij het genereren van de website: style.scss
Lettertypen voor de website.
Afbeeldingen die alleen nodig zijn voor het raamwerk van de website.
Javascript, uitsluitend ten behoeve van zoeken (/zoek.html).
In deze map staan lijsten die worden verwerkt in allerlei webpagina's, zoals.
articles.yml: lidwoorden.search.yml: de tekst die op de zoekpagina in een lege zoekbalk en bij het aantal resultaten staat als de zoekopdracht geen, één, of meerdere resultaten heeft opgeleverd.stopwords.yml: veelgebruikte woorden die worden genegeerd bij het zoeken.
HTML-bestanden die de basis vormen voor de te genereren website.
default.htmlpage.htmltekst.html
Stylesheets waaruit bij het genereren van de website de .css-stylesheets worden afgeleid via /system/assets/css/style.scss.
In deze map staat statische tekst die wordt verwerkt in allerlei webpagina's, maar die niet zelfstandig een pagina vormen en geen eigen URL op de website krijgen.
tekst-faq-intro.md: generieke tekst die staat meteen onder de tekst uit/_teksten/abc.md, maar boven de lijst van gerelateerde artikelen.tekst-item-top.md: generieke tekst die staat boven de tekst uit/_teksten/abc.mdnadat je eerst in de zijbalk Teksten hebt geselecteerd en daarna hebt gekozen voor tekst abc.tekst-taglist-intro.md: generieke tekst die staat meteen onder de lijst van artikelen en boven het overzicht van de labels uit de front matter van/_teksten/abc.md.tekst-item-bottom.md: generieke tekst die helemaal onderaan de pagina van/_teksten/abc.mdstaat, net boven de voettekst.teksten-top.md: generieke tekst die staat boven het overzicht dat wordt getoond als je in de zijbalk Teksten selecteert.- _
teksten-bottom.md: _generieke tekst die staat onder het overzicht dat wordt getoond als je in de zijbalk Teksten selecteert. footer.md: de tekst die onderaan elke pagina tussen het copyright-jaartal en de datum en tijd van de websiteversie staat.welcome-top.md: de generieke tekst die boven de inhoudsopgave op de startpagina staat.welcome-bottom.md: de generieke tekst die onder de inhoudsopgave op de startpagina staat.zoek-intro.md: de tekst die boven de zoekbalk op de zoekpagina staat.
In deze map staan statische pagina's die niet doorverwijzen naar artikelen. Het verschil met de snippets is dat notes zelfstandig een pagina vormen en wel een eigen URL krijgen op de website. Notes worden altijd aangeroepen vanuit de Markdowntekst van de gebruiker en niet door het systeem.
Een snelkoppeling naar een toelichtingspagina met de voorbeeldtitel toelichtingstitel wordt als volgt aangeroepen vanuit een Markdowntekst:
Achtergrondinformatie over dit onderwerp vindt u [hier]({%- include markdownlink.liquid collection="notes" field="title" value="toelichtingstitel" -%}).
De tekst die niet tussen accolades staat, kan natuurlijk naar wens worden aangepast.
De beschrijvingen van de teksten waarmee artikelen in /_artikelen/ via de front matter kunnen worden gemarkeerd.
afbeeldingen/abc.mdxyz.md
Alle afbeeldingen moeten worden geplaatst in de map afbeeldingen/ die in dezelfde map staat als het tekstbestand met de verwijzing. Bijvoorbeeld  in het bestand /_artikelen/tekst.md verwijst naar de afbeelding /_artikelen/afbeeldingen/plaatje.svg. De enige uitzondering hierop zijn verwijzingen vanuit de generieke teksten in de map /_snippets/, omdat deze tekstbestanden worden geïmporteerd in bestanden die in een andere map staan.
Diagrammen als stroomschema's, volgordediagrammen, projectplanningen kun je met Mermaid volledig specificeren binnen een Markdown-document. Dat gebeurt bij voorkeur in Liquid met highlight-blokken die zijn gemarkeerd als Mermaid-code. Dat doe je bijvoorbeeld voor een stroomdiagram op deze manier:
{% highlight mermaid %}
graph TB
A-->B
A-->C
B-->D
C-->D
{% endhighlight %}
Of anders in Markdown met codeblokken die zijn gemarkeerd als Mermaid-code:
```mermaid
graph TB
A-->B
A-->C
B-->D
C-->D
```
Hierin geeft de eerste regel met {% highlight mermaid %} of alleen ```mermaid het begin aan van het Mermaid-blok en de laatste regel met {% endhighlight %} of alleen ``` het einde. Deze regels ertussen specificeren het diagram in Mermaid-taal:
graph TB
A-->B
A-->C
B-->D
C-->D
Probeer altijd de standaardopmaak van de website te gebruiken. Als dat echt niet lukt, kun je een eigen opmaak definiëren op basis van CSS. Zo geef je op de volgende manier de stappen B en D uit het voorbeeld cursieve tekst op een rode achtergrond:
```mermaid
graph TB
A-->B
A-->C
B-->D
C-->D
classDef mijnopmaak font-style:italic,fill:#ff0000
class B,D mijnopmaak
```
Deze eigen opmaak geldt alleen binnen het diagram en vervangt de betreffende opmaakinstellingen van de standaardopmaak. Als de standaardopmaak wijzigt, kan je eigen opmaak slecht leesbaar worden terwijl je misschien niet eens weet dat de standaardopmaak is gewijzigd. Wees daarom terughoudend met eigen opmaakregels. Als je ze toch nodig hebt, moet je de betreffende diagrammen steeds even handmatig controleren als je vermoedt dat de standaardopmaak is aangepast.
Meer informatie over hoe je diagrammen kunt maken met Mermaid, vind je hier.
Hier vind je een live editor waarmee je interactief Mermaid-diagrammen kunt ontwerpen. Let wel op dat de opmaak en configuratie hier iets anders kunnen zijn dan op de website van de Praktijkhandleiding.
Als een webpagina een Mermaid-diagram bevat, moet je in de front matter van die pagina deze regel opnemen om de browser opdracht te geven om de Mermaid-software te laden:
mermaid: true
Dit staat niet standaard aan, omdat de browser van de gebruiker anders onnodig vaak een groot bestand moet laden. Houd er ook rekening mee dat gebruikers bij het laden van een pagina langer moeten wachten naarmate een webpagina meer van deze diagrammen bevat.
Voor een klikbare snelkoppeling naar een pagina binnen de website neem je een extra coderegel op in de specificatie van het diagram, zodat GitHub Pages bij het genereren van de website het juiste adres kan opnemen in de webpagina, bijvoorbeeld:
click A {% include doclink.liquid itemtitle="Voorbeeld" itemcollection="artikelen" %}
De code in dit voorbeeld verwijst bij knooppunt A van een stroomschema naar een document uit de map _artikelen die in de front matter bij title de titel voorbeeld heeft (of Voorbeeld of vooRBeeLd).
Omdat GitHub Pages de webpagina-adressen toewijst, mogen diagrammen geen hardcoded snelkoppelingen naar andere webpagina's binnen deze website bevatten. Je loopt anders het risico dat de koppeling bij een volgende versie van de website niet meer werkt. Snelkoppelingen naar webpagina's buiten deze website, dus buiten het domein van de parameter baseurl uit _config.yml, maak je wel hardcoded en zullen dus verbreken als het adres van de bestemming wijzigt. Voor een klikbare snelkoppeling naar een pagina buiten deze website neem je conform de documentatie van Mermaid bijvoorbeeld de volgende coderegel op in de specificatie van een diagram:
click A "https://www.kadaster.nl"
Deze paragraaf geldt alleen voor webpagina's binnen deze website. Voor verwijzingen naar elders heb je geen keus en kun je niet anders dan het adres hard overtypen en hopen dat het voorlopig niet zal veranderen. Als een dergelijk adres op veel plekken nodig is, kan er overigens wel een variabele voor worden aangemaakt in
\_config.yml. Die kun je dan bijvoorbeeld aanroepen met[{{ site.catalogus_bag_label -}}]({{- site.baseurl -}}{{- site.catalogus_bag_url -}}){:target="blank"}.
De uiteindelijke inhoud van de praktijkhandleiding staat in de map /_artikelen/. De informatie in de andere mappen dient om de metagegevens te definiëren waarmee informatie aan elkaar wordt verbonden of voor de technische inrichting van de website.
Voor het verbinden van informatie gebruikt de website front matter. Dit is een verzameling van variabelen met hun waarden die helemaal bovenaan een bestand staat. De front matter wordt voorafgegaan door een regel met alleen drie minnetjes. En ook meteen erna staat zo'n regel.
Dit is een voorbeeld van front matter:
---
layout: default
title: Gemeentelijke herindeling en gemeentegrenswijzigingen
date: 2018-07-01
editor: "Kadaster"
attributen: identificatie
relaties: ligt in
objecttypen: woonplaats, openbare ruimte, nummeraanduiding
trefwoorden: gemeentelijke herindeling
begrippen: bronhouder
---
Verwijzen naar andere bestanden van de website gebeurt met name via de front matter van elk bestand. Dit is het bovenste gedeelte van elk bestand (tussen de regels met ---), waarin variabelen staan die dienen als metagegevens of parameters bij de inhoud van het bestand. De metagegevens zijn bedoeld om de informatie te verbinden en de parameters beïnvloeden de werking van de websitesoftware. Tegenover elk metagegeven bij een bestand moet een ander bestand staan dat de waarde van het metagegeven als titel heeft. De naam en de waarde van dergelijke parameters moeten exact overeenkomen (zie elders in deze beschrijving).
Rechtstreeks met een Markdown-koppeling verwijzen naar de kop ## 4.5 Titel van de paragraaf in het bestand /_artikelen/voorbeeld.md, is technisch mogelijk met [verwijstekst]({{-site.baseurl-}}/artikelen/voorbeeld#45-titel-van-de-paragraaf), maar de semantische betekenis van zo'n koppeling is niet machine-leesbaar. Dit maakt zulke verwijzingen ongeschikt om ze als linked data te ontsluiten. Daarnaast zal een dergelijke koppeling ophouden te werken als de naam van het doelbestand verandert, wat extra beheerwerk oplevert. De kans daarop is nog groter bij een volledig uitgeschreven websiteadres als [verwijstekst](https://imbag.github.io/praktijkhandleiding/artikelen/voorbeeld#45-titel-van-de-paragraaf (dus zonder {{-site.baseurl-}}). Dan gaat het namelijk ook mis als de locatie van de website verandert, bijvoorbeeld voor een testomgeving.
De Catalogus bevindt zich in een aparte map en hebben een speciale layout, namelijk book. Bij deze bestanden is het belangrijk dat elke paragraaf (of deelparagraaf) een aparte pagina vormt en dat elke ouderpagina via het gegeven subpages: verwijst naar alle bijbehorende kindpagina's (en dus niet andersom). Elke pagina, ongeacht ouder of kind, moet een kop hebben op het hoogste hoofdstukniveau, dus bijvoorbeeld # Hoofdstuktitelin Markdown. Binnen deze map is het mogelijk om te verwijzen naar elke willekeurige hoofdstuk- of paragraafkop. Je doet hierbij alsof de kop waarnaar je verwijst in hetzelfde bestand staat als de verwijzing zelf. De software van de website zorgt er dan voor dat deze verwijzing het doet. Ook hier doen deze verwijzingen niet mee voor linked data, dus neem ze ook op in de front matter bij de regel catalogus:.
Een verwijzing naar de paragraaf # 2.1.5 Mijn voorbeeldparagraaf, ziet er standaard bijvoorbeeld uit als zie [paragraafvoorbeeld](#215-mijn-voorbeeldparagraaf). Hierbij is #215-mijn-voorbeeldparagraaf de slug van de paragraaftitel. Deze kun je bijvoorbeeld te weten komen door in de browser de id van de kop op te vragen (in Chrome doe je dit bijvoorbeeld door vanuit het contextmenu voor Inspecteren te kiezen) of in de statusbalk te kijken naar de URL waarnaar de kop verwijst.
Je kunt ook zelf een id aan een kop toekennen met een block inline attribute list, bijvoorbeeld:
# 2.1.5 Mijn voorbeeldparagraaf
{:#ditismijnid}
De verwijzing naar deze paragraaf wordt dan:
[paragraafvoorbeeld](#ditismijnid)
En in de front matter behoort dan tevens te staan:
catalogus: 2.1.5 Mijn voorbeeldparagraaf, 3.5 Een andere paragraaf
Neem printonly: true op in de front matter van een (afwijkende) pagina de pagina uit te sluiten van het kruimelpad en om onderaan de pagina geen koppelingen naar andere pagina's te tonen. Andere pagina's kunnen ook niet terugverwijzen. Je kunt de naam van deze variabele (nu: printonly) wijzigen. Pas hiervoor de waarde bij flag: in _data/print.yml en bij defaults: in _config.yml aan.
In de front matter staat in beginsel altijd een volgende regel:
date: 2018-07-01
Deze datum bepaalt wat bovenaan komt de staan in de tijdlijn. De tijdlijn attendeert gebruikers op wijzigingen, maar ze kunnen niet zien wat er is gewijzigd (GitHub houdt weliswaar de volledige historie van alles bij, maar GitHub Pages publiceert alleen de actuele versie). Als er inhoudelijk niets verandert, maar alleen een poging wordt gedaan om de leesbaarheid of vindbaarheid van de pagina op de website te verbeteren, hoeft niemand zijn of haar manier van werken aan te passen. Er is dan geen reden om de pagina bovenaan de tijdlijn te willen zetten en dus moet de datum dan niet wijzigen. Dit is bijvoorbeeld het geval als alleen de front matter wijzigt.
In dit voorbeeld is de datum 1 juli 2018. Tenzij het gaat om een beleidskader, is dit dus de dag waarop deze pagina voor het eerst is gepubliceerd of voor het laatst inhoudelijk is gewijzigd. Bij beleidskaders en andere teksten die formeel zijn vastgesteld, is de datum gelijk aan de officiële datum (dus ongeacht de datum waarop iets in de Praktijkhandleiding is verschenen of gewijzigd).
De volgende metagegevens zijn gedefineerd voor de front matter van de artikelen in _artikelen:
---
layout: default
title:
date: 2018-06-28
description: ""
editor: ""
attributen:
beleidskaders:
beslisboomvragen:
gebeurtenissen:
kwaliteitsrapporten:
modeldocumenten:
objecttypen: woonplaats, openbare ruimte, nummeraanduiding, standplaats, ligplaats, pand, verblijfsobject
relaties:
trefwoorden:
---
Je kunt vaak meerdere waarden toekennen aan een variabele. Dat doe je door die waarden achter elkaar te zetten. Soms is het voldoende als er een spatie tussen staat, maar meestal moet er een komma tussen staan. Soms moet je waarden die uit meerdere woorden bestaan, tussen aanhalingstekens zetten, zoals meestal bij de titel. Soms mogen aanhalingstekens juist niet, zoals bij de namen van gerelateerde gebeurtenissen! Dit is voorlopig nog een kwestie van uitproberen. Dat geldt ook voor het gebruik van hoofdletters binnen front matter. Belangrijk is dat de title: - ongeacht het gebruik van hoofdletters of kleine letters! - uniek moet zijn binnen een map en dat de naam van het bestand gelijk is aan de slug van de titel (meestal komt dit neer op alle leestekens verwijderen en de spaties vervangen door een streepje -), gevolgd door.md.
De overzichtpagina's van de meeste metagegevens hebben de volgende front matter:
---
layout: overview
siteindex: true
title: Tekst
sortkey: 000
sortorder: alphabetical
harvest: teksten
---
De titel en beschrijving van een metagegeven, die wordt ingevoerd bij title: (hier in dit voorbeeld: Tekst) en description:, mag geen dubbele punten : (gebruik: :), geen komma's , (gebruik: ,), geen nummertekens # (gebruik: #) en geen Markdownopmaak bevatten. De dubbele punt wordt al gebruikt om de naam van het metagegeven of de parameter te scheiden van de waarden en de komma dient om meerdere waarden van metagegevens of parameters van elkaar te onderscheiden. Alle tekst uit de front matter wordt niet als Markdown opgemaakt, maar als platte tekst gebruikt. Eventuele Markdowncodes worden daardoor zichtbaar op de website, bijvoorbeeld in automatisch gegenereerde lijsten. Als de waarde van een metagegeven enkele ' of dubbele " aanhalingstekens bevat, kan het misschien nodig zijn om om het geheel dubbele of enkele aanhalingstekens te zetten, bijvoorbeeld: title: 'Dit is een "bijzondere" titel'.
De parameter sortorder kan de waarden alphabetical, chronological of sortkey hebben en bepaalt hoe lijstitems worden gesorteerd. Bij chronological komt de nieuwste bovenaan te staan, maar worden geen items zonder datum getoond. Bij sortkey staat de laagste sorteercode bovenaan (let op voorloopnullen worden genegeerd bij het sorteren, dus beter met een letter of met bijvoorbeeld 100 beginnen). Bij andere waarden wordt oplopend alfabetisch gesorteerd.
Het is eenvoudig mogelijk om zelf metagegevens toe te voegen. Dit doe je voor het nieuwe metagegeven met de naam tekst als volgt (let goed op hoofdletters/kleine letters en op meervoud/enkelvoud):
-
Kopieer bijvoorbeeld
/_layouts/objecttype.htmlnaar/_layouts/tekst.html -
Wijzig in
/_layouts/tekst.htmlde codeartikel.objecttypeninartikel.teksten -
Maak de map
/_teksten/aan voor de beschrijvingen van de verschillende waarden van het metagegeven tekst. -
Voeg aan de lijst met
collections:in/_config.ymltoe:
teksten:
output: true
zoeken: true
taggable: true
datums: false
origin:
alias:
referralHighlighting: true
-
Verander
zoeken: trueinzoeken: falseals de bestanden in de map/_teksten/buiten de zoekresultaten van de website moeten worden gelaten (dit heeft geen invloed op externe zoekmachines, zoals Google en DuckDuckGo). -
Verander
taggable: trueintaggable: falseals het metagegeven niet als tag moet worden getoond onderaan pagina's. -
Verander
referralHighlighting: trueinreferralHighlighting:als `taggable: false``. -
Verander
referralHighlighting: trueinreferralHighlighting: falseals na het klikken op een tag de woorden van de tag niet moeten worden gemarkeerd op de doelpagina van de tag. -
Verander
alias:inalias: kruimelpadnaamals niet de naam van de collectie moet worden getoond in het kruimelpad, maar de kruimelpadnaam. -
Verander
datums: falseindatums: trueals de datum van een onderwerp uit de collectie (date:in front matter) moet worden getoond op de pagina van dat onderwerp. (In lijsten wordt de datum altijd getoond.) -
Verander
origin:inorigin: herkomstcollectieom het kruimelpad uit te breiden met een herkomstcollectie die verwijst naar onderwerpen in deze collectie. -
Voeg de volgende bestanden toe aan
/_snippets/:- teksten-top.md:
- teksten-bottom.md
- teksten-item-top.md
- teksten-faq-intro.md
- teksten-item-bottom.md
-
Begin deze bestanden met de volgende front matter:
title:, gevolgd door de hiervoor genoemde naam van het bestand zonder extensie. Bijvoorbeeld:
---
title: teksten-top
---
-
Kopieer bijvoorbeeld
/objecttypen.htmlnaar/teksten.html. -
Wijzig de regel met
title: Objecttypenintitle: Teksten. -
Wijzig de code
site.objecttypeninsite.teksten. -
Pas het getal bij
sortkeyaan, zodat het thema op de gewenste plek in de zijbalk en op de beginpagina komt te staan. -
Beschrijf de verschillende waarden van het metagegeven tekst, zoals abc en xyz, in de bestanden
abc.md,xyz.md, etc. in de map/_teksten/. -
Je kunt het nieuwe begrip/thema Tekst nu gebruiken door aan de front matter van de relevante artikelen in
/_artikelen/bijvoorbeeld toe te voegen:
teksten: abc, xyz
Bij lange artikelen kan het handig zijn om in de zijbalk de paragraaftitels te tonen van het artikel. Dit doe je door in de front matter de parameter toc: op te nemen, met daaronder de exacte title: van de relevante hoofdstuk- en paragraafkoppen in de gewenste volgorde. Je negeert hierbij het hoofdstukniveau. Bij artikelen met een subpages: gebeurt dit alles automatisch. Als front matter zowel een toc: als een subpages: bevat, gaat toc: voor.
Als je gebruik wilt maken van toc:, mogen de paragraaftitels geen dubbele punten :, geen komma's ,, geen nummertekens #, en geen afbreekstreepjes - bevatten, maar :, ,, # en een non-breaking hyphen (Unicode ‑) mogen wel.
Een voorbeeld:
toc:
- Paragraaftitel een
- Paragraaftitel 2
- Paragraaftitel 2.1.7
- Paragraaftitel 2.3
Alternatief kun je een inhoudsopgave tonen bovenaan het artikel (maar deze verschijnt niet in de zijbalk). Dit doe je door bij dat artikel tussen de front matter en de eerste regel van het artikel de volgende code in te voegen:
## Inhoud
{:.no_toc}
* ToC
{:toc}
----
Om te controleren of de verwijzingen op de website kloppen, ga je naar https://imbag.github.io/praktijkhandleiding/beheer. Deze webpagina is niet bereikbaar vanuit de menustructuur van de Praktijkhandleiding, maar alleen door het webadres in te typen. Op deze webpagina staan alle pagina's van de Praktijkhandleiding waarop een of meer van de volgende fouten is geconstateerd:
- Pagina's die naar zichzelf verwijzen;
- Pagina's met dezelfde
title:als andere pagina's in dezelfde collectie (map); - Bronpagina's die verwijzen naar doelpagina's die (nog?) niet bestaan;
- Bronpagina's die meerdere keren verwijzen naar dezelfde doelpagina.
Pagina's waar geen andere pagina's naar verwijzen, hoeven niet onjuist te zijn. Ze zijn herkenbaar doordat er op de betreffende webpagina's geen koppelingen staan naar andere webpagina's.
Het overzicht wordt bij elke aanpassing van de website vernieuwd.
Je kunt vanuit een repository maar één GitHub Pages-website genereren. Om te kunnen testen, moet je daarom een kopie maken van een momentopname van de productieomgeving. Hiertoe maak je eerst een nieuwe private repository aan op GitHub. De naam van de repository, wordt de naam van de website, net zoals dat bij repository "praktijkhandleiding", die je kunt vinden op de webpagina https://github.com/imbag/praktijkhandleiding, de GitHub Pages-website https://imbag.github.io/praktijkhandleiding hoort. Laat het vinkje bij "Initialize this repository with a README" weg en laat "Add .gitignore: None ▾" en "Add a license: None ▾" op None staan.
Als voorbeeld maken we hier een testomgeving en dus een repository aan met de naam testwebsite. Ga naar de instellingen van de nieuwe repository en autoriseer iedereen die schrijfrechten nodig heeft via https://github.com/imbag/testwebsite/settings/collaboration. Zet ook de GitHub Pages-website aan op https://github.com/imbag/testwebsite/settings. Dit doe je door onder het kopje GitHub Pages de source master branch te selecteren. (De waarschuwing "⚠︎ Caution: This repository is private but the published site will be public.", kun je negeren.)
Kloon de nieuwe repository met GitHub Desktop naar je computer. De repository is dan nog leeg. Kopieer vervolgens alle mappen en bestanden van de Praktijkhandleiding integraal naar de map van de nieuwe repository. Gebruik hierbij de juiste versie van de Praktijkhandleiding. Dat mag de laatste commit van de master zijn, maar ook een eerdere commit naar keuze. Onthoud deze commit!
Bewerk nu op je computer de inhoud van de map met de kloon van de nieuwe repository:
- Verwijder de verborgen map
/.git(indien aanwezig); - Pas in
/_config.ymlde regel die begint metbaseurl:aan aan de naam van de nieuwe repository, dus in dit voorbeeldbaseurl: /testwebsite.
Gebruik nu GitHub Desktop om de inhoud die je hebt klaargezet te synchroniseren met GitHub. Commit hiertoe de wijzigingen en neem in de beschrijving van deze commit op op welke commit je de testomgeving hebt gebaseerd (dit is de commit die je een paar stappen terug moest onthouden). Deze informatie kan namelijk later nog eens nodig zijn en is anders nauwelijks meer te achterhalen, omdat je de testomgeving op de beschreven manier namelijk vult met alleen een momentopname van de bron, zonder de historie.
De nieuwe testomgeving is nu klaar voor gebruik.