Houd de Markdown-tabelbron leesbaar door cellen met spaties op te vullen en elke kolom na langere bewerkingen opnieuw uit te lijnen. Bewerk op een Mac met Obsidian de tabel in de ingebouwde tabelbewerker en controleer daarna de bronmodus. De opvulling in de bron en de uitlijning van de weergegeven tekst moeten afzonderlijk worden gecontroleerd.

Deze werkwijze is bedoeld voor iemand die een kleine Markdown-tabel bijhoudt in een desktopnotitie: een leeslijst, een inventaris van schrijfwaren of een projectchecklist. Het doel is de tekst zelf gemakkelijk scanbaar te houden wanneer vermeldingen veranderen, terwijl de tabel in de bedoelde renderer goed blijft werken.

Waardoor is de bron van een Markdown-tabel leesbaar?

Een leesbare brontabel heeft herkenbare kolomgrenzen, consistente spatiëring en één volledige rij per regel. De pipes staan verticaal onder elkaar wanneer de tabel in een lettertype met vaste tekenbreedte wordt weergegeven. In de documentatie van GitHub staat uitdrukkelijk dat cellen niet even breed hoeven te zijn en dat de bronkolommen niet perfect uitgelijnd hoeven te zijn. Deze uitlijning is dus handig bij het bewerken, maar geen vereiste voor een geldige tabel. Informatie ordenen met tabellen.

Deze synthetische tabel is bijvoorbeeld compact, maar wordt moeilijker te scannen nadat een langere itemnaam is ingevoerd:

| Item | Finish | Count |
| --- | --- | ---: |
| Pencil | Matte | 4 |
| Large sketchbook | Linen | 12 |

Door spaties toe te voegen, is dezelfde inhoud als platte tekst gemakkelijker te controleren:

| Item             | Finish | Count |
| ---------------- | ------ | ----: |
| Pencil           | Matte  |     4 |
| Large sketchbook | Linen  |    12 |

In GFM worden spaties tussen de pipegrenzen en de celinhoud verwijderd. Opvulling bepaalt dus niet de breedte van de weergegeven kolom. De dubbele punt in ----: bepaalt dat de weergegeven kolom rechts wordt uitgelijnd; de spaties vóór 4 maken dit bronvoorbeeld alleen gemakkelijker te scannen. GitHub Flavored Markdown-spec, tabellen.

Behandel dit als twee afzonderlijke keuzes: kies opvulling om de bron leesbaar te maken en kies dubbele punten in de scheidingsrij om weergegeven tekst uit te lijnen. Als je enige probleem is dat de pipes in de editor niet gelijk staan, lossen andere dubbele punten dat niet op.

Welke renderer verwerkt de tabel?

Pipe-tabellen zijn een uitbreiding en geen onderdeel van de kern van CommonMark. De huidige CommonMark-specificatie verwijst naar versie 0.31.2, terwijl de gepubliceerde GFM-specificatie van GitHub tabellen uitdrukkelijk definieert als een uitbreiding op CommonMark. Een renderer die alleen als compatibel met CommonMark wordt beschreven, biedt daarmee niet automatisch ondersteuning voor pipe-tabellen. Controleer of deze ook een tabeluitbreiding ondersteunt. CommonMark-spec, GitHub Flavored Markdown-spec.

De volgende verschillen zijn van belang wanneer je een notitie tussen toepassingen verplaatst:

Bestemming Gedocumenteerd gedrag Praktische keuze
Core CommonMark De kernspecificatie bevat geen pipe-tabelsyntaxis Controleer of er een tabeluitbreiding beschikbaar is
GitHub Volgens de tabelgids moeten scheidingscellen minstens drie koppeltekens bevatten Gebruik --- of meer
Obsidian De tabelgids accepteert minimaal twee koppeltekens en vereist niet dat de broncellen uitgelijnd zijn Gebruik drie of meer als je ook GitHub als bestemming hebt

De bovenstaande vereisten voor koppeltekens komen uit de handleidingen van de respectieve producten. Minstens drie gebruiken is een handige gedeelde conventie voor deze twee bestemmingen; daardoor worden niet alle Markdown-renderers gelijkwaardig. GitHub-tabeldocumentatie, Geavanceerde opmaaksyntaxis van Obsidian.

Gebruik voor een tabel die bedoeld is voor zowel Obsidian als GitHub een pipe aan het begin en einde, gewone spaties als opvulling en een lege regel vóór en na de tabel. In de gids van GitHub staat dat er een lege regel aan de tabel vooraf moet gaan; de GFM-specificatie vermeldt dat een lege regel de tabel beëindigt. Door beide grenzen expliciet aan te geven, is de bron ook gemakkelijker te herkennen. GitHub-tabeldocumentatie, Tabelgrenzen in GFM.

De tabel bijhouden in Obsidian op een Mac

Obsidian biedt een handige werkwijze voor wie cellen gemakkelijk wil bewerken en daarna leesbare Markdown wil overhouden. In de release notes van versie 1.5.8 voor desktop werd automatische tabelformattering tijdens het typen geïntroduceerd, met specifiek de vermelding dat kolommen er netter uitzien in de bronmodus. Dit is gedocumenteerd gedrag van de editor, geen functie van de Markdown-syntaxis. Release notes van Obsidian 1.5.8 voor desktop.

Gebruik voor een gewone notitie deze stappen:

  1. Open de notitie in Live Preview. Selecteer deze modus indien nodig via het statuspictogram van de editor.
  2. Voeg een tabel in met de opdracht Insert Table of klik met de rechtermuisknop en kies Insert → Table.
  3. Voer de celinhoud in of pas deze aan in de tabelbewerker. Klik met de rechtermuisknop op de tabel als je rijen en kolommen wilt toevoegen, verwijderen, verplaatsen of sorteren.
  4. Selecteer Source mode via het statuspictogram en controleer de resulterende Markdown.
  5. Schakel over naar Reading view om de weergegeven tabel te controleren.

De modusbediening wordt beschreven in Weergaven en bewerkingsmodus; het invoegen van tabellen en de bewerkingen via het contextmenu worden beschreven in Geavanceerde opmaaksyntaxis.

Als je vaak tussen modi wisselt, wijs dan een sneltoets toe aan Toggle Live Preview/Source mode. Op macOS wissel je met Cmd+E tussen de lees- en bewerkingsweergave; gebruik de speciale modusopdracht als je specifiek tussen de twee bewerkingsmodi wilt schakelen. Weergaven en bewerkingsmodus van Obsidian.

Als rechtstreeks typen in Source mode ongelijke opvulling oplevert, keer dan terug naar de ingebouwde tabelbewerker om verder te bewerken en controleer daarna de bron. De aangehaalde documentatie beschrijft automatische tabelformattering en nauwkeurige broninspectie, maar garandeert niet dat elke willekeurige bewerking van de bron direct opnieuw van opvulling wordt voorzien. Bij een kleine tabel die ongelijk blijft, biedt de handmatige methode hieronder directe controle.

Bronkolommen opnieuw uitlijnen na een langere bewerking

Gebruik een eenvoudige regel: maak elke bronkolom breed genoeg voor de langste huidige vermelding, inclusief de kop. Vul de andere cellen in die kolom op. Bereken de opvulling opnieuw wanneer een vermelding langer wordt dan de beschikbare ruimte.

Hier volgt een uitgewerkt voorbeeld met alleen gewone ASCII-tekst. Begin met deze tabel:

| Item   | Finish | Count |
| ------ | ------ | ----: |
| Pencil | Matte  |     4 |
| Folder | Linen  |    12 |

Vervang nu Folder door Large sketchbook. Het nieuwe item heeft 16 tekens, dus de eerste kolom moet ruimte bieden aan 16 tekens. Laat direct binnen elke begrenzende pipe één spatie staan en voeg daarna genoeg spaties aan het einde toe om die ruimte te vullen:

  • Item heeft 4 tekens, dus voeg er 12 opvulspaties achter toe, gevolgd door de begrenzende spatie.
  • Pencil heeft 6 tekens, dus voeg er 10 opvulspaties achter toe, gevolgd door de begrenzende spatie.
  • Large sketchbook vult de ruimte van 16 tekens, dus heeft daarna alleen de begrenzende spatie nodig.
  • Verleng de eerste scheidingscel tot 16 koppeltekens als visuele richtlijn.

Het resultaat is de eerder getoonde opgevulde tabel. Alleen de eerste kolom moest breder worden. De andere kolommen behouden hun spatiëring en uitlijnmarkeringen.

Dit is een handmatige opmaakmethode voor het genoemde ASCII-voorbeeld, geen algemeen algoritme voor tekenbreedte. Controleer voor dagelijks gebruik het resultaat in een bronweergave met vaste tekenbreedte. Als cellen veel inlineopmaak bevatten, bepaal de bronbreedte dan op basis van de tekens die daadwerkelijk zijn geschreven, inclusief leestekens zoals backticks en sterretjes.

Lijn de tabel na een reeks bewerkingen één keer uit in plaats van na elke toetsaanslag elke rij aan te passen. Als vermeldingen vaak alinea’s worden, overweeg dan om alleen een kort label in de tabel te zetten en de toelichting eronder in gewone tekst te plaatsen. Zo hoef je minder witruimte bij te houden zonder informatie uit de tekst te schrappen.

Wat controleer je als een tabel niet meer werkt?

Controleer eerst de structuur voordat je spaties aanpast. Volgens GFM moeten de kop- en scheidingsrij evenveel cellen bevatten. Rijen in de tabelinhoud met te weinig cellen krijgen lege cellen; overtollige cellen worden genegeerd. Daardoor kan een tabel er aannemelijk uitzien terwijl de weergegeven versie inhoud weglaat. Regels voor het verwerken van GFM-tabellen.

Volg deze stappen om problemen op te sporen na een ingrijpende bewerking:

  1. Vergelijk de kop- en scheidingsrij. Geef elke kop een bijbehorende scheidingscel.
  2. Controleer elke rij in de tabelinhoud. Behoud het bedoelde aantal cellen, ook wanneer een waarde leeg is.
  3. Zoek naar letterlijke pipes in de inhoud. Een niet-escapete pipe kan als extra grens worden geïnterpreteerd.
  4. Controleer de rijgrenzen. Houd elke tabelrij op één bronregel en vermijd lege regels in de tabel.
  5. Bekijk een voorbeeld van de bestemming. Controleer zowel de weergegeven waarden als het uiterlijk van de tabel.

Voor letterlijke pipes beschrijft GitHub dat je een backslash vóór het teken plaatst. In dit volledige voorbeeld blijft Blue | Green in één cel:

| Item   | Options       |
| ------ | ------------- |
| Folder | Blue \| Green |

De escape is structureel; meer spaties rond een niet-escapete pipe lossen dit niet op. Voorbeeld van een letterlijke pipe op GitHub.

Obsidian beschrijft ook hoe je de pipe in een interne-linkalias in een tabel escapt. Dit is een specifieke syntactische overweging voor Obsidian. Dat een alias is geescapet, bewijst op zichzelf dus niet dat links op dezelfde manier werken op GitHub. Richtlijnen voor tabelopmaak in Obsidian.

Druk niet halverwege een lange cel op Enter om de bron smaller te laten lijken. GFM-tabellen accepteren inline-inhoud en sluiten elementen op blokniveau uit; ze bieden geen algemene indeling voor cellen met meerdere bronregels. Verplaats lange toelichtingen buiten de tabel wanneer rijen met één regel onpraktisch worden. Regels voor tabelinhoud in GFM.

Houd de onderhoudsroutine klein: werk de inhoud bij, controleer de celgrenzen, vul de betreffende kolommen opnieuw op en bekijk de weergegeven tabel. In Obsidian is de ingebouwde tabelbewerker, gevolgd door Source mode, een praktisch uitgangspunt. Handmatige opvulling blijft handig wanneer je een bepaalde indeling als platte tekst wilt.

Bronnen