# Gemtext-to-HTML parser Enter gemtext in the upper textarea and click “Parse” to convert it to raw HTML in the lower textarea and render it at the bottom (on narrower screens) or on the right (on wider screens). Read on for more info, and click “Reset” to revert to this info (be careful: you can't undo the reset). This parser has nothing to do with any gemini protocol people or organisations. => https://geminiprotocol.net/ => gemini://geminiprotocol.net/ ## What's gemtext? Gemtext is a super-light markdown-like syntax used over the gemini protocol, an alternative plaintext internet protocol. You get just a handful of content types, all of them block-level (so no inline bold or italic, links in paragraphs, etc.): * 3 levels of heading * regular paragraphs * bullet point lists * blockquotes * links (always on separate lines) * pre-formatted text You can't use HTML, and you can't nest elements inside other elements. => https://geminiprotocol.net/docs/gemtext.gmi Introduction to gemtext on the gemini protocol site => https://git.skyjake.fi/gemini/lagrange/releases Latest releases of Lagrange, the graphic gemini browser => https://portal.mozz.us/gemini/gemini.circumlunar.space/ Project Gemini original homepage via the Smolnet Portal => https://geminiprotocol.net/docs/faq-section-1.gmi#112-the-gentler-answer-for-everybody-else As for why people might use such a simple protocol and syntax... ## Gem style Save the file at the link below for a CSS file that styles the output of this parser to look like gemtext (while still being HTML). => ./gem-style.css gem-style CSS ## How the parser handles gemtext ### Escaped HTML You can't write HTML in gemtext (unlike markdown), so the first thing the parser does is to “escape” various bits of HTML code. First, it finds all HTML entities (e.g. — for an em dash) and changes the ampersand with its own HTML entity (&). Second, it changes angle brackets (< and >) into their HTML entities (< and >). The result: all HTML in your gemtext gets parsed into its raw text. => https://www.w3schools.com/html/html_entities.asp HTML entity tutorial ### Strictness This parser's a little stricter than “official” gemtext. All headings, blockquotes, and links must have a single space after their marker, and labelled links must have a single space between their URL and label. ```code: strict gemtext demo: all the gemtext below is technically valid, but only the “correct” ones, with whitespace, work in this parser # correct -> <h1>correct</h1> #incorrect -> <p>#incorrect</p> > correct -> <blockquote><p>correct</p></blockquote> >incorrect -> <p>>incorrect</p> => correct -> <a href="correct">correct</a> =>incorrect -> <p>=>incorrect</p> ``` ### Linebreaks If two or more gemtext paragraphs are on one line after the other the parser converts them to a single HTML paragraph split by <br> elements (HTML linebreaks). ### Lists Sets of list items get wrapped in <ul> elements, no matter how many newlines or other whitespace is between them. For example: * The Ghost in Science * Virtual Rabbit * Aurora * Sim City * Siren * Technique of Relief ### Blockquotes The text of a blockquote is wrapped in <blockquote> tags, then <p> tags. Multiple blockquotes can be merged together in two ways. > By putting them on adjacent lines... > ...which also combines them into... > ...one paragraph with linebreaks. Or: > By putting an empty blockquote marker between two blockquotes (there can be any number of empty lines above or below the empty marker)... > > ...two blockquotes can be combined into one, while still keeping the paragraphs separate. You can combine both ways in the same overall blockquote. These patterns are taken from how I've seen people write gemtext in real files to show that two quote-lines are part of the same quote (they don't have any effect in gemtext, though). ### Links All links are wrapped in <div> tags as an easy way to keep them on separate lines without needing CSS. => https://geminiprotocol.net/docs/cheatsheet.gmi Gemtext cheatsheet => https://example.com/ If you write a link on the line directly after a blockquote (as a source/citation), both elements will be merged into a captioned <figure>: > You will not be saved by General Motors or the pre-fabricated house. > You will not be saved by dialectic materialism or the Lambeth Conference. > You will not be saved by Vitamin D or the expanding universe. > In fact, you will not be saved. => https://allpoetry.com/Nightmare,-With-Angels from “Nightmare, With Angels”, by Stephen Vincent Benét ### Preformatted text The problem with pre-formatted blocks in gemtext is that people use the same pattern for so many different things: pure decoration, images that need alt-text, captioned visual information, code samples that need to be read as plaintext... The parser converts all of these to the same basic structure in HTML: a <pre> element wrapped in a <figure> element. However, you can specify the type of pre-formatted text using the description written after the opening backtick fence (```), which modifies the HTML. Types consist of a prefix word, then a colon, then a space. Here are the types: * If it starts with “text”, “code”, or “sample”, then the block is raw text, like a code example or a poem. The description is added to a <figcaption> element above the text. If the prefix is “code” or “sample” then the content of the <pre> element will be wrapped in <code> or <samp> tags. * If it starts with “caption”, then the block is visual information, like a chart, diagram, or image. The <pre> block is marked with aria-hidden and the description is copied to a <figcaption> element above the text. * If it starts any other way (including no description), then the block is pure decoration. The entire <figure> is marked with aria-hidden. Here's an example of ASCII art with an explanatory caption: ```caption: The Legend of Zelda: Link's Awakening title ASCII art, from a spoiler-free walkthrough on GameFAQs || _||_ | | THE LEGEND OF ______| |_______ ______________ ______ ____ / ____| |__ / \ __ \ / \ "\ \_ \ / / | | / / | | \ | | | |"\ | \ \ /__/ _| |/ / / | | \_| | | | | | | \ / __ / / / | |_/| | | | | | | | \ /_/| / / / | | | | | | | | | /_\ \ |/ / | |_ | | | | | | | ; __ \ / / / | | \/ _| | || | | | / / \ \ / / / | |___/ / |/|| |_/ |/ / \ \ / /| __|______/|____|/______//___\ /___\ / / / | / / / / / | / / LINK'S AWAKENING / / /| |____/ / /_____| |______/ - - - - - - - - - - | | | | SPOILERFREE WALKTHROUGH \ / \/ ``` => https://gamefaqs.gamespot.com/gameboy/563277-the-legend-of-zelda-links-awakening/faqs/34994 image source (artist: Kaas) And here's an example of a raw text code sample, with the language in the caption: ```code: CSS pre { overflow-x: auto; } ``` Finally, here's a purely decorative pre-formatted block that should be ignored by accessibility apps: ``` ~~~~~ * ~~~~~ ``` It's a little complex and clunky, but this is my best attempt to make an easy-to-use and accessible distinction between all these use-cases. ## The controls ### Browse The “Browse…” button lets you open a .gmi, .gemini, or .txt file in the input area. ### Parse The “Parse” button parses the gemtext into HTML, then displays the raw code in the bottom, read-only, textarea, and renders it after that. ### Reset The “Reset” button resets the parser, so it shows this default gemtext and its raw and rendered HTML. ## Under the hood First, the parser splits the input into chunks using the backtick fences (``` at the start of a line). The odd-numbered chunks are regular text and the even-numbered chunks are pre-formatted text. Pre-formatted text gets processed according to its description, and regular text gets processed for every other bit of syntax. The parser makes heavy use of regular expressions (regex). I tried making a line-by-line parser, and while it was a few times faster in relative terms, it only saved milliseconds in absolute terms and the code was longer and less readable. ## Parsing HTML to gemtext? This sounds nice in theory, but there are way too many problems in practice: * nesting: HTML allows it, gemtext doesn't * the unaccounted elements: how do you parse <ol>, <table>, <details>–<summary>, etc.? * flexibility: there are many ways to accomplish things in HTML that can be done only one way in gemtext, which means the parser needs to standardise (according to whose standards?) Markdown avoids some or all of these due to its complexity and the fact that it's a superset of HTML (that is, you can use HTML in markdown since it's meant to be parsed to HTML anyway). Gemtext doesn't have that freedom, so some of these problems are impossible to overcome. Parse Reset