KIST Banner

Keep It Simple Text Markup (KIST)

Users Guide by Richard Rathe, v0.17, December 2024

KIST combines the best elements of various markup formats I've worked with over the past forty years. The original purpose of these tools was to quickly generate valid HTML. The plain text source files are nearly universal and reusable!

Other possible targets for automated conversion are BLIS Journaling, Wordpress (depreciated), and ePub Books. To get a better feel for how KIST works, review the KIST Source for this familiar book rendered as an HTML Booklet or eBook. A Quick Reference is also available.

KIST aspires to the Least Ink Principle proposed by Edward Tufte in 1983 (paraphrased): The best documentation is that which gives to the reader the greatest amount of information in the shortest time with the fewest pixels.

KIST aspires to Fail Gracefully when something isn't quite right.

KIST uses Open Standards whenever and wherever possible!

Basic Rules


Line Level Elements

These elements affect entire lines of text and provide the overall structure of the document. A basic layout is very simple…

  Document Title (<h1>)

  text, lists, tables…

  #Heading 1 (<h2>)

  more content…

  #Heading 2 (<h2>)

  etc…

Paragraphs (<p>)

Generic text not otherwise marked up will flow into paragraphs.

This is a paragraph
of words that are on
different lines.
Quisque viverra,
ligula vitae aliquam
vulputate.

Next element starts here…

This is a paragraph of words that are on different lines. Quisque viverra, ligula vitae aliquam vulputate.

Next element starts here…

Note that inline images (discussed below) are technically line level elements and behave like paragraphs.

Headings (<h1> etc.)

Full Hierarchy

#	One # <h2>
##	Two ## <h3>
###	Three ### <h4>
####	Four #### <h5>
#####	Five ##### <h6>

Lists (<ul>, <ol>)

Simple List Example

List Title Example

A single leading ^ after first <tab> indicates a title.

	^List of Fruit
	apple
	banana
	orange

Ordered List Example

A single leading # after first <tab> indicates an ordered list <ol>.

	#Lorem ipsum dolor… etc.
  1. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Curabitur eu augue. Nunc sollicitudin felis sed purus. Morbi libero tellus, laoreet sed, fringilla id, nonummy in, sapien. Nulla facilisi.
  2. Integer a eros vitae felis scelerisque gravida.
  3. Cras orci justo, porttitor ut, suscipit et, ornare ut, velit. Proin orci tellus, pulvinar eu, consectetuer ut, faucibus vitae, tellus.

Nested List Example

  1. one
  2. two
    • abc
      1. uno
      2. dos
        • left
        • right
      3. tres
    • def
    • ghi
      1. up
      2. down
  3. three
    • jkl

Preformatted Text (<pre>)

Lines beginning with equals signs = are passed through as is with no additional formatting. Note that long lines can extend far beyond the right margin of the page!

 line 1 Integer a *eros vitae* felis scelerisque gravida.
 line 2 Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Pellentesque ullamcorper odio in ipsum.

 line 4 Note the extra     spaces!

Tables

Simple Table Example

1 2 3
4 5 6
7 8 9

Table with Column Headings and Empty Cells

Col1 Col2 Col3 Col4
felis scelerisque accumsan eu nonummy quis justo pellentesque euismod quis pretium ut leo quis justo
eleifend consectetuer pellentesque
viverra augue in elit mauris

Block Quoting (Email Style)

Compatible with email systems that use leading > chars for quotation. This is especially useful for formating poetry or verse. Note that nested quotations (>>, etc.) are not supported.

>Twinkle, twinkle, little bat!
>  How I wonder what you're at!
>
>>Up above the world you fly,
>>  Like a tea-tray in the sky.
Twinkle, twinkle, little bat!
  How I wonder what you're at!

Up above the world you fly,
  Like a tea-tray in the sky.

Comments

Comment lines begin with a single quote ' and may be ignored in most output formats. Comments can also be used to hide metadata elements as described below.

'List
'of
'Comments

Horizontal Rule (<hr>)

Line begins with at least three dashes.

--- text is ignored, can be used as a comment

Text Level Markup

These elements occur within paragraphs, lists, etc. and cannot span lines.

Name/Value Elements

^name(value)

Hypertext Links

Link to the ^Weather Forecast(https://forecast.weather.gov/).

Link to the Weather Forecast.

Valid local file extensions are: html htm txt text pdf

Link to ^Local File(kist-guide.txt) in the same directory.

Link to a Local File in the same directory.

Link to a ^Section(#s3) in the same document.

Link to a Section in the same document.

Non-local images will be linked but not embedded.

Link to ^Remote Image(https://mdpaths.com/kist/alice/img/the-caterpillar.jpg).

Link to Remote Image.

Images

Inline Images

These images are responsive and will shrink or grow with the browser window. Alt Text appears as a visible caption and is never hidden.

^Alt Text(kist_images/picture.jpg)
Alt Text
Alt Text

Images that are smaller than the document will not grow beyond 100%. Note the reference link in square brackets. References are discussed below.

^Smaller Flower Photo [3](kist_images/picture2.jpg)
Smaller Flower Photo [3]
Smaller Flower Photo [3]

Placeholders are a way to quickly add an image without specific alt text.

^placeholder(kist_images/picture2.jpg)
picture2.jpg
picture2.jpg

It is often useful to have smaller inline images that are linked to full-sized versions. This is indicted by the suffix -sm at the end of the filename. KIST assumes there is a corresponding image by the same name (without -sm) and will link to it. You cannot have reference and image links in the same element.

^Small Image with Link(kist_images/picture4-sm.jpg)
Small Image with Link
Small Image with Link

It is also possible to have inline images within block quotes.

>Block Quote with an Inline Image
>
>^Smaller Flower Photo(kist_images/picture2.jpg)
>
>End Block
Block Quote with an Inline Image
Smaller Flower Photo
Smaller Flower Photo


End Block

Floating Images

These images are limited to 25-33% of the document width and will float to the right of the paragraph text that follows. Note that there is currently no way to clear these floats, so images may overflow if there is not enough text.

^Carl Sagan(carl_sagan.png) Floating Paragraph…
Carl Sagan
Carl Sagan

Floating Paragraph… Are creatures of the cosmos Orion's sword dream of the mind's eye network of wormholes invent the universe hundreds of thousands. The only home we've ever known stirred by starlight encyclopaedia galactica preserve and cherish that pale blue dot courage of our questions rich in heavy atoms?

Note that this is a normal paragraph following the floating image paragraph above. The image may or may not overlap depending on the size of the display… Astonishment stirred by starlight hundreds of thousands a mote of dust suspended in a sunbeam extraordinary claims require extraordinary evidence with pretty stories for which there's little good evidence.

Embedded Images (Depreciated)

Eliminated in favor of the simpler formats outlined above.

Image Galleries

This is a quick & dirty approach to formatting images into useful contact sheet style galleries. The individual file names become the captions for each image. It is up to the user to provide meaningful file names.

For example…

 ^Rock Art Gallery(kist_gallery/)

Impromptu Slide Shows

  1. Click on any image to view the first slide.
  2. The full-sized image appears in a pop-up window.
  3. Click anywhere on the image to go to the next slide.
  4. Click anywhere outside of the image to end the show.

Embedded Video & Audio

Use the kind=video_id format to embed a media clip (as opposed to linking to it).

This is a provisional feature. Other media types and sources may be possible in the future.

Youtube

^Vermilion Cliffs Video(youtube=69KjOHNljaE)

Note that Youtube videos embedded in this way will attempt to contact youtube even when not being viewed. Make sure your browser prevents this or avoid this feature entirely if you have concerns!

Local MP4 File

^Local MP4 File(video=kist_media/kayak-sailing.mp4)

Local MP3 File

^Local MP3 File(audio=kist_media/purple-martins.mp3)

Metadata

Metadata provide information about the document, tagging the author's name for example. The actual text is left in place, but the name=value pairs can be used elsewhere as needed.

^author(Joe Blow), ^date(March 1, 2021), etc.

Use a comment (see above) to completely hide metadata.

'^permalink(https://mdpaths.com/kist/) ^hidden(metadata)

The permalink name has special meaning, it specifies the permanent address (URL) for the document.

References & Footnotes

A Reference (footnote/endnote) is a special type of list item that starts with square brackets []. There are two possible styles: Numeric and Textual. These IDs must be unique within the document and cannot contain other links.

Lists of references may occur anywhere in the document (typically at the ends of sections or the end of the document). They can be used alone or with reference links.[2]

Reference Links

Reference links allow the reader to quickly find notes and reference material. In plain text, simply search on the [ref] id (which should be unique). In HTML, these links will bring up references in a pop-up dialog box to prevent scrolling away from the text. Links to references may appear more than once in the same document.

Numeric reference links take this form and can be used `multiple` times.

A Numeric Footnote^[1]

A Numeric Footnote[1]

Textual reference links must begin with a letter and cannot contain spaces or punctuation.

Author/Year Style Footnote^[Author2008]

Author/Year Style Footnote[Author2008]

There is also a sample endnote at the bottom[4] of this document.

Stylistic Markup

None of these elements can span lines!

Emphasis (<em>)

Surround text with stars * for emphasis.

You should *not* do that.

You should not do that.

Inline Quotes (<q>)

Surround text with double quotes.

Everyone should read "Walden" by Thoreau.

Everyone should read Walden by Thoreau.

Highlighting/Redlining (<ins>, <del>)

Surround text with curly brackets {} to indicate inline editorial comments, recent changes, or highlighting. Surround text with hyphens '-' to indicate deleted or erroneous text. Note that the trailing '-' must have a space after it to distinguish deleted text from normal hyphenation.

This is -old text- {new text} about a topic.

This is old text new text about a topic.

The following sentence has hyphenation, stray hyphens, and nested curly brackets to demonstrate how these elements interact. Note that they do not nest.

Made in the anti-matter of collapsing stars—the -cosmic ocean Apollonius of Perga two ghostly white figures in coveralls and {helmets are softly dancing hydrogen atoms from which} we spring?

Hashtags/Keywords

Under Development, Subject to Change

Hashtags are commonly found in Social Media posts. They are an informal way to indicate keywords, topics, or threads. They often consist of phrases made up of multiple words. There are several equivalent formats:

  #word
  #word_word2
  #wordWord2 (camel case)
  #WordWord2 (caps case)
Use a hash # before words to indicate a #hashtag.
Underscores tie_words_together into #multi_word_phrases.
Mid-phrase capitalization indicates a #WordBoundary.
These hashtags are equivalent #WordBoundary, #wordBoundary, & #Word_Boundary.
Note that outside this context underscores '_' have no special meaning.

Use a hash # before words to indicate a hashtag. Underscores tie_words_together into multi word phrases. Mid-phrase capitalization indicates a Word Boundary. The hashtags Word Boundary, word Boundary, & Word Boundary are equivalent. Note that outside this context underscores '_' have no special meaning.


Action Journaling (AJ)

!!	AJ Item Examples
.	open task (.)
!	open priority task (!)
?	open query/decision task (?)
~	completed task (~)
|	deferred/reassigned task (|)

*Note that the title element (!!) is new and the deferred flag (|) has changed from (\). The choice of markup characters is not arbitrary. AJ task lists will sort correctly based on ASCII order.


My History of Textual Tinkering


Oddments/Bugs/Gotchas


External Links
 https://mdpaths.com/rrr/projects/kist_markup/kist_guide/index.html (permalink)
 https://mdpaths.com/rrr/books/alice_in_wonderland/alice.txt
 https://mdpaths.com/rrr/books/alice_in_wonderland/index.html
 https://mdpaths.com/rrr/books/alice_in_wonderland/alice-in-wonderland.epub
 https://forecast.weather.gov/
 https://mdpaths.com/kist/alice/img/the-caterpillar.jpg
 https://mdpaths.com/aj/
 https://richard.rathe.org/hypertext-before-the-world-wide-web
 https://mdpaths.com/kist/kist_images/kist-awk-book.jpg
 https://mdpaths.com/aj/
 https://mdpaths.com/kist/kist_images/kist-tabletop.png
 https://richard.rathe.org/2023/keep-it-simple-text-kist

This is a slide!