KIST to HTML Conversion Notes
KIST Markup by Richard Rathe, v0.17, December 2024
Conversion Program
Kist.pl is a Perl script run from the command line as follows…
kist: keep it simple text conversion usage: kist [-cmfbiwsxqvd] file [file2…] -c make comments visible -m add metadata to footer -f supress document footer -b supress booklet view -i output 'index.html' file -w wordpress compatible output (text only) * -w=http… wordpress output path to images * -s=custom.css use custom stylesheet -x xhtml output for ebook -q quiet mode (not yet!) -v verbose mode (not yet!) -d debugging mode (show extra detail) (not yet!) *depreciated, will be removed in future versions version 0.17 by richard rathe 2024 cc attribution-share-alike license
Output files (.html) have the same name as source files (.txt) unless the -i flag is set. The parser supports the #! shebang
directive on the first line for the above flags.
#! -b -m
(booklet off, metadata on)
Default Output
- Standard CSS/HTML Page
- File Name Same as Source
- Booklet View (Navigation)
- Comments Hidden
- Minimal Footer
Minimal Style
Kist.pl renders documents as plain vanilla
HTML by default.
Generated pages will degrade gracefully
to the degree possible.
These pages contain a minimal set of CSS styles in the <head> element.
Authors are free to replace these styles with
their own custom styles (using the -s flag).
Special Characters
Support for common plain text idioms:
- double-dashs — become an em dash
- three periods … become an ellipsis
- dash- greater-than → becomes a right arrow
- quotes are
smartened
(<q>)
The special HTML characters <, >, & are escaped.
Minimal Footer
By default output files will have a minimal footer containing the version of kist.pl that generated the page and the timestamp when the source file was last updated.
kist: 0.17 - Dec 21, 2024 08:51
Metadata
The -m flag will display the metadata associated with the document.
author: Richard Rathe † category: programming † converted: Dec 21, 2024 09:20 date: December 2024 † edited: Dec 21, 2024 09:20 generator: Keep It Simple Text (KIST) v0.17 hashtags: css,css_styles,html,perl ‡ keywords: programming,css,css styles,html,perl § kist: 0.17 permalink: https://mdpaths.com/kist/kist-html.html † source: kist-html.txt version: 0.17 †
† defined by ^name(value) elements in text ‡ social-media style #hashtags in text § 'keywords' combine categories and hashtags
Hierarchical Organization
HTML has several elements that organize information hierarchically. Headings (h1 through h6) help create outlines or chapters. (For practical purposes only # h2 and ## h3 are really useful.) Lists (ul, ol) may contain many sublists (aka Nested Lists).
KIST does not check documents for structural errors. The author must ensure headings are properly used and lists are well formed.
Linkable Sections
Top level headings also divide the document into sections that can be linked to using the # section name format. Sections are labeled s0
, s1
, etc. Here is a standard HTML link to the second heading/section in a hypothetical document:
…index.html#s2
Intra-document links are possible using regular markup.
^See Above(#s2) (link to second section)
See Above (link to second section)
References are another possible target for links. They are labeled ref1
, ref2
. etc.
Sticky Headings
<h1> and <h2> headings use the sticky
CSS attribute, allowing them to persist at the top as each section scrolls underneath.
List Titles
The HTML standard does not support a title or caption for lists as it does for tables. Various authors have suggested solutions to this problem, none are perfect. For KIST I've opted to treat the first item of the list as the title when needed.
^List Title one two three
Which renders as…
- List Title
- one
- two
- three
Or…
<ul> <li class="title">List Title</li> <li>one</li> <li>two</li> <li>three</li> </ul>
Tabs to Tables
The Tab (aka Horizontal Tab
) is one of the few ASCII control characters routinely used today. It indicates format rather than content. A TSV file has values (data fields) separated by tabs. This is similar (and superior) to the more well-known CSV (comma separated values) format—because commas are both separators and part of the data! This leads to confusion, special escape codes, and a whole lot of quotation marks!
KIST uses TSV-formatted data directly as its table format.
1 2 3 4 5 6 7 8 9
1 | 2 | 3 |
4 | 5 | 6 |
7 | 8 | 9 |
Alt Text
Missing or erroneous alt text for images is a persistent problem for web developers. KIST pages treat images the same as links with the name=value construct. This ensures the text and visual data always stay together. KIST adds both alt text and title attributes to every image tag.
^Missing Image Example(kist-booklet.png)

Reference Links
Reference links are a quick way to show notes and references without scrolling away from the main text. (The actual reference text appears elsewhere in the document.)
Some text with a reference link.^[1]

A reference link will bring up a dialog box with the desired text. Click anywhere outside the box to dismiss the dialog.
Print CSS
A minimal set of media-specific styles are included to optimize printing. If a page contains external links, these appear in the footer. For example…
External Links On This Page https://mdpaths.com/kist/mtxformat.txt https://forecast.weather.gov/ https://mdpaths.com/everglades2023c.jpg https://mdpaths.com/aj/
'Booklet' Navigation
Longer documents require increasing amounts of scrolling for navigation. (This is mitigated somewhat by the search function in the browser.) In the past I would have used a hypertextual solution, breaking the document into multiple pages with navigation links between.
In this era of responsive content optimized for small vertical screens, KIST takes a simpler approach. The Booklet View is toggled by a '☰' button in the upper right corner of each page.

Each major section (defined by the top level #
headings) collapses to a clickable stub
. The reader is then free to navigate with minimal scrolling and focus on a single section at a time. This has the appearance of a card file or folded page. Clicking on the X
button will exit the booklet view.

Clicking on any section will open just that section. The reader is free to scroll, click, and selectively read the entire document in this fashion.

Booklet Demo (11.2Mb MP4 File)
Example Booklet (Alice in Wonderland)