# Gemtext ## Vad det är Gemtext är dokumentformatet i protokollet Gemini: vanlig text i UTF-8 där de första tecknen på varje rad avgör vad raden är, så att en klient kan rendera en hel sida i ett enda svep uppifrån och ned. Specifikationen kallar det Geminis hypertextformat, servrar märker det med medietypen `text/gemini` och filerna slutar enligt konvention på `.gmi`. Det finns sex sorters rader. En rad som börjar med `=>` är en länk, med en adress, absolut eller relativ, och en valfri etikett efter den. En rad med tre backticks slår på eller av förformaterat läge, och allt som står mellan två sådana rader visas exakt som det skrevs, i ett typsnitt med fast bredd. En, två eller tre brädgårdar gör en rubrik, en asterisk följd av ett mellanslag gör en listpunkt och en rad som börjar med `>` blir ett citat. Alla andra rader är vanlig text, och klienten radbryter dem efter bredden på den skärm de hamnar på. ```text # Field notes A text line is a paragraph, however long it runs. The client wraps it. => /archive/ Older notes => gemini://example.org/ A capsule elsewhere * A list item > A quoted line ``` Specifikationen delar in de sex i tre kärntyper som varje klient måste hantera (text, länkar och växeln för förformaterat läge) och tre som en minimal klient får visa som vanlig text. Det är hela formatet. Det saknar fetstil, kursiv, tabeller, bilder i löptexten och nästling, och det går inte att göra ett ord mitt i en mening klickbart. En parser håller reda på en enda bit tillstånd: om den befinner sig i ett förformaterat block eller inte. Gemtext jämförs oftast med Markdown, som det liknar vid första anblick. Skillnaden ligger i vad de är till för. En Markdown-fil är en källfil, skriven för att omvandlas till något annat. En gemtext-fil är redan det färdiga dokumentet, och läsarens klient är den enda som renderar det. Sin enda strukturella vana, länken på en egen rad, har formatet lånat från de äldre menyerna i Gopher. ## Varför det spelar roll Att välja gemtext är att välja vem som styr sidan. Författaren bestämmer strukturen: vilka rader som är rubriker, vilka som är länkar och var koden står. Läsarens klient bestämmer resten, från typsnitt och radlängd till färg, avstånd och om rubrikerna blir en innehållsförteckning. Specifikationen säger rakt ut att formatet inte är tänkt att ge författare exakt kontroll över presentationen. För en del utgivare är det en lättnad, och för andra är frågan därmed avgjord. Det lönar sig att veta vilket innan man konverterar en enda sida. Lättnaden ligger i det som försvinner. En sida i gemtext bär ingen stilmall, inget skript, inget webbtypsnitt, ingen fråga om samtycke till kakor och ingen spårningspixel, och det enda som någonsin behöver uppdateras är orden. Sidorna blir små och går snabbt att skriva för hand. Länkar hämtar aldrig något på egen hand, eftersom specifikationen förbjuder en klient att öppna en nätverksanslutning bara för att visa en länk. En sida kan alltså inte dra in en bild eller ett typsnitt från tredje part bakom läsarens rygg. Kostnaden är lika konkret. Gemtext når bara de som kör en Gemini-klient, och det är en liten publik jämfört med webbens. Formatet har inga formulär: det enda sätt en kapsel kan be om inmatning är en statuskod i protokollet, aldrig något i dokumentet. Och prosan måste fungera utan länkar inne i meningarna. En mening skriven för HTML, ”se prissidan för detaljer”, behåller sina ord men tappar sin pekare. Att skriva bra gemtext är därför att skriva meningar som fortfarande går att förstå när länken står på raden under. Därför gäller den realistiska frågan för de flesta organisationer gemtext utöver en webbplats, inte gemtext i stället för en, framställt från samma källa av samma bygge. Ställd på det sättet kostar gemtext lite att lägga till, och det fungerar samtidigt som ett test av texten. Läses en sida fortfarande tydligt som en kolumn av textrader och länkrader, så satt strukturen i orden hela tiden. ## Så ser det ut i praktiken Den här webbplatsen publiceras som gemtext vid sidan av sin HTML. Sidan [Engineer i en terminal](/sv/cli/) anger kapselns adress, `gemini://engineer.company/`, säger att varje sida på webbplatsen också finns i formatet och nämner klienter som läser det: Amfora, Lagrange och Bombadillo i en terminal, Castor och Kristall i ett fönster. Den ger också skälet. En driftsättning skriver en mapp som varje ytterdörr läser, så kopian i gemtext kan inte glida isär från HTML-koden, och en sida som läses bra som gemtext är en sida vars struktur är verklig snarare än pålagd. Hur det byggdes står i [redogörelsen för hur webbplatsen speglades till Gemini och Gopher](/sv/portfolio/mirrored-the-site-to-gemini-and-gopher-137/). Gemtext är ett utdataformat i samma bygge, inte en separat pipeline. Webbplatsgeneratorn fick egna medietyper och utdataformat, och varje sida, sektion och taxonomiterm fick ett Gemini-dokument vid sidan av sin HTML och sin Markdown-tvilling: 777 stycken, serverade av en liten daemon på samma värddator. De nya formaten är markerade som icke-alternativa representationer, så HTML-koden ändrades inte med en enda byte, och det mättes snarare än antogs. De alternativa representationerna kostar ungefär tolv procent av HTML-kodens egen vikt på disk. Mallarna bakom den kopian visar vad en konvertering till gemtext innebär. Varje länk inne i en mening lyfts ut: orden stannar där meningen behöver dem, och adressen flyttar ned under texten som en egen `=>`-rad. Markeringar för fetstil tas bort, punkter med bindestreck blir asterisker, och ett kodblock mellan tre backticks passerar orört, eftersom Markdown och gemtext ramar in sådana block med samma tre tecken. ## Var det går fel ### Halva rader som aldrig fogas ihop Prosan kommer fram i klienten som en ojämn kolumn av korta rader, brutna mitt i en sats. Källan var hårt radbruten vid 80 kolumner, som Markdown-filer ofta är, och specifikationen förbjuder en klient att foga ihop korta textrader som följer på varandra till längre. Skriv varje stycke som en enda lång rad, eller låt konverteraren foga ihop mjuka radbrytningar innan den skriver filen. ### Länkar som lämnar kapseln Den första länken en läsare följer öppnar en webbläsare. Konverteraren skrev varje länk som en absolut `https://`-adress, och en Gemini-klient lämnar över sådana adresser till ett annat program. Skriv navigeringen som sökvägar från roten, t.ex. `/about/`, som löses upp inne i kapseln, och behåll en avsiktlig länk per sida till sidans webbversion. ### Kod som faller ihop till en enda rad Ett kodexempel visas som en enda lång rad som sitter fast i sin inledande rad med backticks. Konverteraren behandlade blocket som prosa och fogade ihop dess rader med allt annat. Dela upp dokumentet vid kodblockens gränser före alla andra steg, släpp igenom varje förformaterat block precis som det skrevs och låt växelraden bära högst en kort alternativtext, t.ex. språkets namn. ### Markdown som blir till bokstavliga tecken Punkter med bindestreck, dubbla asterisker, understrukna rubriker, nästlade listor och länkar inom hakparenteser dyker upp i klienten exakt som de skrevs. Gemtext känner bara igen en asterisk och ett mellanslag som listpunkt och brädgårdar som rubrik, och formatet har ingen markering alls inne i löptexten. Konvertera de konstruktionerna på vägen ut, eller skriv kapseln direkt i gemtext. ### Meningar som pekar på ingenting Ett stycke säger ”klicka här” eller ”som länkas ovan”, och läsaren har ingen aning om vart det leder. Länken lyftes ut ur meningen, och orden som blev kvar sa aldrig vart den gick. Skriv länketiketter som namnger sitt mål, så att både meningen och `=>`-raden går att förstå var för sig. ## Läs mer - [A quick introduction to gemtext markup](https://geminiprotocol.net/docs/gemtext.gmi) — projektets egen korta genomgång av varje radtyp, med anteckningar för den som kan Markdown. - [Gemini hypertext format specification](https://geminiprotocol.net/docs/gemtext-specification.gmi) — den normativa texten: radtyper, parserns tillstånd, regler för radbrytning, parametern `lang` och en formell grammatik. - [Gemini network protocol specification](https://geminiprotocol.net/docs/protocol-specification.gmi) — hur en kapsel serverar gemtext: förfrågningar, statuskoder och de regler för TLS som en klient följer. - [Project Gemini FAQ](https://geminiprotocol.net/docs/faq.gmi) — resonemanget bakom designen, bl.a. varför länkar står på egna rader.