.
Use # to ##### leading hashs for to .
It is up to the author to nest these properly!
Whitespace following # will be ignored for readability.
## Full Hierarchy
=# One #
=## Two ##
=### Three ###
=#### Four ####
=##### Five #####
# Lists (, )
Lists are unordered by default.
A *leading tab* indicates a list item - .
Use \ chars when you cannot type tabs (web forms).
Add space for clarity with a tab followed by a period.
The number of tabs determines nesting.
It is up to the author to nest these properly!
## Simple List Example
tree
apple
pencil
## List Title Example
A single leading ^ after first
indicates a title.
= ^List of Fruit
= apple
= banana
= orange
^List of Fruit
apple
banana
orange
## Ordered List Example
A single leading # after first indicates an ordered list .
= #Lorem ipsum dolor... etc.
#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.
.
Integer a eros vitae felis scelerisque gravida.
.
Cras orci justo, porttitor ut, suscipit et, ornare ut, velit. Proin orci tellus, pulvinar eu, consectetuer ut, faucibus vitae, tellus.
## Nested List Example
#one
two
abc
#uno
dos
left
right
tres
def
ghi
#up
down
three
jkl
# Preformatted Text ()
Lines beginning with equals signs = are passed through "as is" with no additional formatting.
Note that long lines will 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
Direct use of *tab-separated values* (".tsv" or ".tab" files).
It is up to the author to ensure data consistency!
First char must *not* be a tab (indicating a list item).
A leading ^ char on the first line indicates column headings.
As with lists, \ chars may be used when tabs cannot be typed.
## 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 extra quotations (>>, >>>, etc.) are ignored.
=>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 (
)
Line begins with at least three dashes.
=--- text is ignored, can be used as a comment
--- text is ignored
# Text Level Markup
These elements occur *within* paragraphs, lists, etc. and *cannot span lines*.
= Hypertext Links
=
= Images ![]()
=
= Metadata
=
= Word Level Styles , , , etc.
# Name=Value Elements
=^name{value}
Also referred to as a "key/value" pair.
Used for links, images, and metadata.
This construct cannot span lines.
*Staring with v0.19 the use of () is depreciated.*
=^name(value) -> use ^name{value} instead!
# Hypertext Links
=Link to the ^Weather Forecast{https://forecast.weather.gov/}.
Link to the ^Weather Forecast{https://forecast.weather.gov/}.
=Link to ^Local File{kist-guide.txt} in the same directory.
Link to a ^Local File{kist-guide.txt} in the same directory.
Valid local file extensions are: *html htm txt text pdf*
=Link to a ^Section{#s3} in the same document.
Link to a ^Section{#s3} in the same document.
*Non-local images* will be linked but not embedded.
=Link to ^Remote Image{https://mdpaths.com/...jpg}.
Link to ^Remote Image{https://mdpaths.com/rrr/blis_media/banner-river-pano.jpg}.
# Images
*Inline* images behave like paragraphs and will adjust to the size of the screen.
*Floating* images will appear smaller, embedded within a paragraph.
*Banner* images are a special case and appear above all other markup.
See the top of this document for an example.
Use *relative URLs* for local images (eg, "images/picture.jpg").
"#Alt_Text" should be a *short description* of the image.
The magic word "temp" will default alt text to the file name.
Valid image file extensions are: *jpg jpeg gif png*
## 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{kist_images/picture.jpg}
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]{kist_images/picture2.jpg}
An image with no #alt_text is an error.
^{kist_images/picture2.jpg}
You should instead use the "temp" placeholder as a way to quickly add an image without specific alt text.
=^temp{kist_images/picture2.jpg}
^temp{kist_images/picture2.jpg}
It is often useful to have a *smaller inline image* linked to its *full-sized* version. 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 create a link to it.
You *cannot* have reference and image links in the same element.
'### come back to the above statement, is it still true?? ###
=^Small Image with Link{kist_images/picture4-sm.jpg}
^Small Image with Link{kist_images/picture4-sm.jpg}
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{kist_images/picture2.jpg}
>
>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{kist_images/carl_sagan_1994_float.png} *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.
Galleries use the same general rules for images, formats, etc.
Each gallery has a *title* and a *relative URL* to a directory.
Each gallery image has a hypertext link to its full-sized original.
There can be *multiple galleries* on a single page.
It is assumed the gallery directory contains *only* image files.
Caption text is cleaned up for clarity (capitalized, punctuation removed).
For example...
= ^Rock Art Gallery{kist_gallery/}
^Rock Art Gallery{kist_gallery/}
## Impromptu Slide Shows
#Click on any image to view the first "slide".
The full-sized image appears in a pop-up window.
*Click anywhere on the image* to go to the next "slide".
Click anywhere outside of the image to end the show.
# Embedded Video & Audio
Use the "kind=media" 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}
^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 MP4 File{video=kist_media/kayak-sailing.mp4}
## Local MP3 File
=^Local MP3 File{audio=kist_media/purple-martins.mp3}
^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.* The name=value pairs can be used elsewhere as needed.
=^author{Joe Blow}, ^date{March 1, 2021}, etc.
Joe Blow, March 1, 2021, etc.
Use a comment (see above) to completely hide metadata.
='^permalink{https://mdpaths.com/rrr/} ^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.
[1] This is the first reference.
[2] This is a second longer reference. Use the reference link *[2]* below to access it from anywhere in this document.
99 This is a non-reference item just to show you can mix and match.
[3] This is the third reference. It is linked to from an image.
[Author2008] Author/Year is a popular style used mostly in academic papers.
[Author2008a] Different article by the same author in the same year.
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 ()
Surround text with stars * for emphasis.
=You should *not* do that.
You should *not* do that.
## Inline Quotes ()
Surround text with double quotes.
=Everyone should read "Walden" by Thoreau.
Everyone should read "Walden" by Thoreau.
## Highlighting/Redlining (, )
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 #SocialMedia 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 #WordBoundary.
These hashtags are equivalent: #WordBoundary, #wordBoundary, #word_boundary.
Note that outside this context underscores '_' have no special meaning.
------------------------------
# Action Journaling (AJ)
I developed this ^todo list/journaling format(https://mdpaths.com/rrr/projects/action_journaling/index.html) in 2016.
AJ items are formatted as an unordered list.
White space after first char is ignored for readability.
=!! AJ Item Examples
=. open task (.)
=! open priority task (!)
=? open query/decision task (?)
=~ completed task (~)
=| deferred/reassigned task (|)
!! 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 #UTF8 order.
------------------------------
# My History of Textual Tinkering
1988 ^HYTEXT{../../hypertext_before_the_web/index.html} Hypertext Publishing System for MS-DOS
1989 Conversion of Medical Textbooks with ^AWK{https://richard.mdpaths.com/projects/kist/kist_guide/kist_images/kist-awk-book.jpg} (NLM Fellowship)
1996 ^MTX{mtx-format.text} Marked TeXt for Web Publishing (U of Fla)
1997 Self-Organizing Hypertext Notebooks (^Jrju{../../../medicine/medinfo/self_organizing_hypertext_notebooks/index.html})
2000s ^Action Journaling{https://mdpaths.com/rrr/projects/action_journaling/index.html} for Paper, Computer & Web
2016 ^TableTop{https://richard.mdpaths.com/projects/kist/kist_guide/kist_images/kist-tabletop.png} – Table Manipulation App
2020 Keep It Simple Text (^KIST{../index.html})
------------------------------
# Oddments/Bugs/Gotchas
The first non-blank line must be the document title.
Exceptions are ^-x switches(kist-html.html) and banner images.
The first cell in a table row *cannot be blank*.
Block quote nesting is not supported.
Captions for ordered lists are not supported.
Certain symbols have special meaning:
permalink -> metadata permanent address (URL)
temp -> use file name for image caption
'-sm' image suffix -> link to larger image
The source file must end with a newline.
^Endnote
[4] This is an endnote.
.
It is up to the author to nest these properly!
Whitespace following # will be ignored for readability.
## Full Hierarchy
=# One #
=## Two ##
=### Three ###
=#### Four ####
=##### Five #####
# Lists (, )
Lists are unordered by default.
A *leading tab* indicates a list item - .
Use \ chars when you cannot type tabs (web forms).
Add space for clarity with a tab followed by a period.
The number of tabs determines nesting.
It is up to the author to nest these properly!
## Simple List Example
tree
apple
pencil
## List Title Example
A single leading ^ after first
indicates a title.
= ^List of Fruit
= apple
= banana
= orange
^List of Fruit
apple
banana
orange
## Ordered List Example
A single leading # after first indicates an ordered list .
= #Lorem ipsum dolor... etc.
#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.
.
Integer a eros vitae felis scelerisque gravida.
.
Cras orci justo, porttitor ut, suscipit et, ornare ut, velit. Proin orci tellus, pulvinar eu, consectetuer ut, faucibus vitae, tellus.
## Nested List Example
#one
two
abc
#uno
dos
left
right
tres
def
ghi
#up
down
three
jkl
# Preformatted Text ()
Lines beginning with equals signs = are passed through "as is" with no additional formatting.
Note that long lines will 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
Direct use of *tab-separated values* (".tsv" or ".tab" files).
It is up to the author to ensure data consistency!
First char must *not* be a tab (indicating a list item).
A leading ^ char on the first line indicates column headings.
As with lists, \ chars may be used when tabs cannot be typed.
## 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 extra quotations (>>, >>>, etc.) are ignored.
=>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 (
)
Line begins with at least three dashes.
=--- text is ignored, can be used as a comment
--- text is ignored
# Text Level Markup
These elements occur *within* paragraphs, lists, etc. and *cannot span lines*.
= Hypertext Links
=
= Images ![]()
=
= Metadata
=
= Word Level Styles , , , etc.
# Name=Value Elements
=^name{value}
Also referred to as a "key/value" pair.
Used for links, images, and metadata.
This construct cannot span lines.
*Staring with v0.19 the use of () is depreciated.*
=^name(value) -> use ^name{value} instead!
# Hypertext Links
=Link to the ^Weather Forecast{https://forecast.weather.gov/}.
Link to the ^Weather Forecast{https://forecast.weather.gov/}.
=Link to ^Local File{kist-guide.txt} in the same directory.
Link to a ^Local File{kist-guide.txt} in the same directory.
Valid local file extensions are: *html htm txt text pdf*
=Link to a ^Section{#s3} in the same document.
Link to a ^Section{#s3} in the same document.
*Non-local images* will be linked but not embedded.
=Link to ^Remote Image{https://mdpaths.com/...jpg}.
Link to ^Remote Image{https://mdpaths.com/rrr/blis_media/banner-river-pano.jpg}.
# Images
*Inline* images behave like paragraphs and will adjust to the size of the screen.
*Floating* images will appear smaller, embedded within a paragraph.
*Banner* images are a special case and appear above all other markup.
See the top of this document for an example.
Use *relative URLs* for local images (eg, "images/picture.jpg").
"#Alt_Text" should be a *short description* of the image.
The magic word "temp" will default alt text to the file name.
Valid image file extensions are: *jpg jpeg gif png*
## 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{kist_images/picture.jpg}
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]{kist_images/picture2.jpg}
An image with no #alt_text is an error.
^{kist_images/picture2.jpg}
You should instead use the "temp" placeholder as a way to quickly add an image without specific alt text.
=^temp{kist_images/picture2.jpg}
^temp{kist_images/picture2.jpg}
It is often useful to have a *smaller inline image* linked to its *full-sized* version. 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 create a link to it.
You *cannot* have reference and image links in the same element.
'### come back to the above statement, is it still true?? ###
=^Small Image with Link{kist_images/picture4-sm.jpg}
^Small Image with Link{kist_images/picture4-sm.jpg}
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{kist_images/picture2.jpg}
>
>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{kist_images/carl_sagan_1994_float.png} *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.
Galleries use the same general rules for images, formats, etc.
Each gallery has a *title* and a *relative URL* to a directory.
Each gallery image has a hypertext link to its full-sized original.
There can be *multiple galleries* on a single page.
It is assumed the gallery directory contains *only* image files.
Caption text is cleaned up for clarity (capitalized, punctuation removed).
For example...
= ^Rock Art Gallery{kist_gallery/}
^Rock Art Gallery{kist_gallery/}
## Impromptu Slide Shows
#Click on any image to view the first "slide".
The full-sized image appears in a pop-up window.
*Click anywhere on the image* to go to the next "slide".
Click anywhere outside of the image to end the show.
# Embedded Video & Audio
Use the "kind=media" 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}
^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 MP4 File{video=kist_media/kayak-sailing.mp4}
## Local MP3 File
=^Local MP3 File{audio=kist_media/purple-martins.mp3}
^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.* The name=value pairs can be used elsewhere as needed.
=^author{Joe Blow}, ^date{March 1, 2021}, etc.
Joe Blow, March 1, 2021, etc.
Use a comment (see above) to completely hide metadata.
='^permalink{https://mdpaths.com/rrr/} ^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.
[1] This is the first reference.
[2] This is a second longer reference. Use the reference link *[2]* below to access it from anywhere in this document.
99 This is a non-reference item just to show you can mix and match.
[3] This is the third reference. It is linked to from an image.
[Author2008] Author/Year is a popular style used mostly in academic papers.
[Author2008a] Different article by the same author in the same year.
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 ()
Surround text with stars * for emphasis.
=You should *not* do that.
You should *not* do that.
## Inline Quotes ()
Surround text with double quotes.
=Everyone should read "Walden" by Thoreau.
Everyone should read "Walden" by Thoreau.
## Highlighting/Redlining (, )
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 #SocialMedia 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 #WordBoundary.
These hashtags are equivalent: #WordBoundary, #wordBoundary, #word_boundary.
Note that outside this context underscores '_' have no special meaning.
------------------------------
# Action Journaling (AJ)
I developed this ^todo list/journaling format(https://mdpaths.com/rrr/projects/action_journaling/index.html) in 2016.
AJ items are formatted as an unordered list.
White space after first char is ignored for readability.
=!! AJ Item Examples
=. open task (.)
=! open priority task (!)
=? open query/decision task (?)
=~ completed task (~)
=| deferred/reassigned task (|)
!! 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 #UTF8 order.
------------------------------
# My History of Textual Tinkering
1988 ^HYTEXT{../../hypertext_before_the_web/index.html} Hypertext Publishing System for MS-DOS
1989 Conversion of Medical Textbooks with ^AWK{https://richard.mdpaths.com/projects/kist/kist_guide/kist_images/kist-awk-book.jpg} (NLM Fellowship)
1996 ^MTX{mtx-format.text} Marked TeXt for Web Publishing (U of Fla)
1997 Self-Organizing Hypertext Notebooks (^Jrju{../../../medicine/medinfo/self_organizing_hypertext_notebooks/index.html})
2000s ^Action Journaling{https://mdpaths.com/rrr/projects/action_journaling/index.html} for Paper, Computer & Web
2016 ^TableTop{https://richard.mdpaths.com/projects/kist/kist_guide/kist_images/kist-tabletop.png} – Table Manipulation App
2020 Keep It Simple Text (^KIST{../index.html})
------------------------------
# Oddments/Bugs/Gotchas
The first non-blank line must be the document title.
Exceptions are ^-x switches(kist-html.html) and banner images.
The first cell in a table row *cannot be blank*.
Block quote nesting is not supported.
Captions for ordered lists are not supported.
Certain symbols have special meaning:
permalink -> metadata permanent address (URL)
temp -> use file name for image caption
'-sm' image suffix -> link to larger image
The source file must end with a newline.
^Endnote
[4] This is an endnote.
=### Three ###
=#### Four ####
=##### Five #####
# Lists (, )
Lists are unordered by default.
A *leading tab* indicates a list item - .
Use \ chars when you cannot type tabs (web forms).
Add space for clarity with a tab followed by a period.
The number of tabs determines nesting.
It is up to the author to nest these properly!
## Simple List Example
tree
apple
pencil
## List Title Example
A single leading ^ after first
indicates a title.
= ^List of Fruit
= apple
= banana
= orange
^List of Fruit
apple
banana
orange
## Ordered List Example
A single leading # after first indicates an ordered list .
= #Lorem ipsum dolor... etc.
#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.
.
Integer a eros vitae felis scelerisque gravida.
.
Cras orci justo, porttitor ut, suscipit et, ornare ut, velit. Proin orci tellus, pulvinar eu, consectetuer ut, faucibus vitae, tellus.
## Nested List Example
#one
two
abc
#uno
dos
left
right
tres
def
ghi
#up
down
three
jkl
# Preformatted Text ()
Lines beginning with equals signs = are passed through "as is" with no additional formatting.
Note that long lines will 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
Direct use of *tab-separated values* (".tsv" or ".tab" files).
It is up to the author to ensure data consistency!
First char must *not* be a tab (indicating a list item).
A leading ^ char on the first line indicates column headings.
As with lists, \ chars may be used when tabs cannot be typed.
## 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 extra quotations (>>, >>>, etc.) are ignored.
=>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 (
)
Line begins with at least three dashes.
=--- text is ignored, can be used as a comment
--- text is ignored
# Text Level Markup
These elements occur *within* paragraphs, lists, etc. and *cannot span lines*.
= Hypertext Links
=
= Images ![]()
=
= Metadata
=
= Word Level Styles , , , etc.
# Name=Value Elements
=^name{value}
Also referred to as a "key/value" pair.
Used for links, images, and metadata.
This construct cannot span lines.
*Staring with v0.19 the use of () is depreciated.*
=^name(value) -> use ^name{value} instead!
# Hypertext Links
=Link to the ^Weather Forecast{https://forecast.weather.gov/}.
Link to the ^Weather Forecast{https://forecast.weather.gov/}.
=Link to ^Local File{kist-guide.txt} in the same directory.
Link to a ^Local File{kist-guide.txt} in the same directory.
Valid local file extensions are: *html htm txt text pdf*
=Link to a ^Section{#s3} in the same document.
Link to a ^Section{#s3} in the same document.
*Non-local images* will be linked but not embedded.
=Link to ^Remote Image{https://mdpaths.com/...jpg}.
Link to ^Remote Image{https://mdpaths.com/rrr/blis_media/banner-river-pano.jpg}.
# Images
*Inline* images behave like paragraphs and will adjust to the size of the screen.
*Floating* images will appear smaller, embedded within a paragraph.
*Banner* images are a special case and appear above all other markup.
See the top of this document for an example.
Use *relative URLs* for local images (eg, "images/picture.jpg").
"#Alt_Text" should be a *short description* of the image.
The magic word "temp" will default alt text to the file name.
Valid image file extensions are: *jpg jpeg gif png*
## 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{kist_images/picture.jpg}
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]{kist_images/picture2.jpg}
An image with no #alt_text is an error.
^{kist_images/picture2.jpg}
You should instead use the "temp" placeholder as a way to quickly add an image without specific alt text.
=^temp{kist_images/picture2.jpg}
^temp{kist_images/picture2.jpg}
It is often useful to have a *smaller inline image* linked to its *full-sized* version. 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 create a link to it.
You *cannot* have reference and image links in the same element.
'### come back to the above statement, is it still true?? ###
=^Small Image with Link{kist_images/picture4-sm.jpg}
^Small Image with Link{kist_images/picture4-sm.jpg}
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{kist_images/picture2.jpg}
>
>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{kist_images/carl_sagan_1994_float.png} *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.
Galleries use the same general rules for images, formats, etc.
Each gallery has a *title* and a *relative URL* to a directory.
Each gallery image has a hypertext link to its full-sized original.
There can be *multiple galleries* on a single page.
It is assumed the gallery directory contains *only* image files.
Caption text is cleaned up for clarity (capitalized, punctuation removed).
For example...
= ^Rock Art Gallery{kist_gallery/}
^Rock Art Gallery{kist_gallery/}
## Impromptu Slide Shows
#Click on any image to view the first "slide".
The full-sized image appears in a pop-up window.
*Click anywhere on the image* to go to the next "slide".
Click anywhere outside of the image to end the show.
# Embedded Video & Audio
Use the "kind=media" 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}
^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 MP4 File{video=kist_media/kayak-sailing.mp4}
## Local MP3 File
=^Local MP3 File{audio=kist_media/purple-martins.mp3}
^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.* The name=value pairs can be used elsewhere as needed.
=^author{Joe Blow}, ^date{March 1, 2021}, etc.
Joe Blow, March 1, 2021, etc.
Use a comment (see above) to completely hide metadata.
='^permalink{https://mdpaths.com/rrr/} ^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.
[1] This is the first reference.
[2] This is a second longer reference. Use the reference link *[2]* below to access it from anywhere in this document.
99 This is a non-reference item just to show you can mix and match.
[3] This is the third reference. It is linked to from an image.
[Author2008] Author/Year is a popular style used mostly in academic papers.
[Author2008a] Different article by the same author in the same year.
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 ()
Surround text with stars * for emphasis.
=You should *not* do that.
You should *not* do that.
## Inline Quotes ()
Surround text with double quotes.
=Everyone should read "Walden" by Thoreau.
Everyone should read "Walden" by Thoreau.
## Highlighting/Redlining (, )
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 #SocialMedia 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 #WordBoundary.
These hashtags are equivalent: #WordBoundary, #wordBoundary, #word_boundary.
Note that outside this context underscores '_' have no special meaning.
------------------------------
# Action Journaling (AJ)
I developed this ^todo list/journaling format(https://mdpaths.com/rrr/projects/action_journaling/index.html) in 2016.
AJ items are formatted as an unordered list.
White space after first char is ignored for readability.
=!! AJ Item Examples
=. open task (.)
=! open priority task (!)
=? open query/decision task (?)
=~ completed task (~)
=| deferred/reassigned task (|)
!! 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 #UTF8 order.
------------------------------
# My History of Textual Tinkering
1988 ^HYTEXT{../../hypertext_before_the_web/index.html} Hypertext Publishing System for MS-DOS
1989 Conversion of Medical Textbooks with ^AWK{https://richard.mdpaths.com/projects/kist/kist_guide/kist_images/kist-awk-book.jpg} (NLM Fellowship)
1996 ^MTX{mtx-format.text} Marked TeXt for Web Publishing (U of Fla)
1997 Self-Organizing Hypertext Notebooks (^Jrju{../../../medicine/medinfo/self_organizing_hypertext_notebooks/index.html})
2000s ^Action Journaling{https://mdpaths.com/rrr/projects/action_journaling/index.html} for Paper, Computer & Web
2016 ^TableTop{https://richard.mdpaths.com/projects/kist/kist_guide/kist_images/kist-tabletop.png} – Table Manipulation App
2020 Keep It Simple Text (^KIST{../index.html})
------------------------------
# Oddments/Bugs/Gotchas
The first non-blank line must be the document title.
Exceptions are ^-x switches(kist-html.html) and banner images.
The first cell in a table row *cannot be blank*.
Block quote nesting is not supported.
Captions for ordered lists are not supported.
Certain symbols have special meaning:
permalink -> metadata permanent address (URL)
temp -> use file name for image caption
'-sm' image suffix -> link to larger image
The source file must end with a newline.
^Endnote
[4] This is an endnote.
=##### Five #####
# Lists (, )
Lists are unordered by default.
A *leading tab* indicates a list item - .
Use \ chars when you cannot type tabs (web forms).
Add space for clarity with a tab followed by a period.
The number of tabs determines nesting.
It is up to the author to nest these properly!
## Simple List Example
tree
apple
pencil
## List Title Example
A single leading ^ after first
indicates a title.
= ^List of Fruit
= apple
= banana
= orange
^List of Fruit
apple
banana
orange
## Ordered List Example
A single leading # after first indicates an ordered list .
= #Lorem ipsum dolor... etc.
#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.
.
Integer a eros vitae felis scelerisque gravida.
.
Cras orci justo, porttitor ut, suscipit et, ornare ut, velit. Proin orci tellus, pulvinar eu, consectetuer ut, faucibus vitae, tellus.
## Nested List Example
#one
two
abc
#uno
dos
left
right
tres
def
ghi
#up
down
three
jkl
# Preformatted Text ()
Lines beginning with equals signs = are passed through "as is" with no additional formatting.
Note that long lines will 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
Direct use of *tab-separated values* (".tsv" or ".tab" files).
It is up to the author to ensure data consistency!
First char must *not* be a tab (indicating a list item).
A leading ^ char on the first line indicates column headings.
As with lists, \ chars may be used when tabs cannot be typed.
## 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 extra quotations (>>, >>>, etc.) are ignored.
=>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 (
)
Line begins with at least three dashes.
=--- text is ignored, can be used as a comment
--- text is ignored
# Text Level Markup
These elements occur *within* paragraphs, lists, etc. and *cannot span lines*.
= Hypertext Links
=
= Images ![]()
=
= Metadata
=
= Word Level Styles , , , etc.
# Name=Value Elements
=^name{value}
Also referred to as a "key/value" pair.
Used for links, images, and metadata.
This construct cannot span lines.
*Staring with v0.19 the use of () is depreciated.*
=^name(value) -> use ^name{value} instead!
# Hypertext Links
=Link to the ^Weather Forecast{https://forecast.weather.gov/}.
Link to the ^Weather Forecast{https://forecast.weather.gov/}.
=Link to ^Local File{kist-guide.txt} in the same directory.
Link to a ^Local File{kist-guide.txt} in the same directory.
Valid local file extensions are: *html htm txt text pdf*
=Link to a ^Section{#s3} in the same document.
Link to a ^Section{#s3} in the same document.
*Non-local images* will be linked but not embedded.
=Link to ^Remote Image{https://mdpaths.com/...jpg}.
Link to ^Remote Image{https://mdpaths.com/rrr/blis_media/banner-river-pano.jpg}.
# Images
*Inline* images behave like paragraphs and will adjust to the size of the screen.
*Floating* images will appear smaller, embedded within a paragraph.
*Banner* images are a special case and appear above all other markup.
See the top of this document for an example.
Use *relative URLs* for local images (eg, "images/picture.jpg").
"#Alt_Text" should be a *short description* of the image.
The magic word "temp" will default alt text to the file name.
Valid image file extensions are: *jpg jpeg gif png*
## 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{kist_images/picture.jpg}
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]{kist_images/picture2.jpg}
An image with no #alt_text is an error.
^{kist_images/picture2.jpg}
You should instead use the "temp" placeholder as a way to quickly add an image without specific alt text.
=^temp{kist_images/picture2.jpg}
^temp{kist_images/picture2.jpg}
It is often useful to have a *smaller inline image* linked to its *full-sized* version. 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 create a link to it.
You *cannot* have reference and image links in the same element.
'### come back to the above statement, is it still true?? ###
=^Small Image with Link{kist_images/picture4-sm.jpg}
^Small Image with Link{kist_images/picture4-sm.jpg}
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{kist_images/picture2.jpg}
>
>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{kist_images/carl_sagan_1994_float.png} *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.
Galleries use the same general rules for images, formats, etc.
Each gallery has a *title* and a *relative URL* to a directory.
Each gallery image has a hypertext link to its full-sized original.
There can be *multiple galleries* on a single page.
It is assumed the gallery directory contains *only* image files.
Caption text is cleaned up for clarity (capitalized, punctuation removed).
For example...
= ^Rock Art Gallery{kist_gallery/}
^Rock Art Gallery{kist_gallery/}
## Impromptu Slide Shows
#Click on any image to view the first "slide".
The full-sized image appears in a pop-up window.
*Click anywhere on the image* to go to the next "slide".
Click anywhere outside of the image to end the show.
# Embedded Video & Audio
Use the "kind=media" 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}
^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 MP4 File{video=kist_media/kayak-sailing.mp4}
## Local MP3 File
=^Local MP3 File{audio=kist_media/purple-martins.mp3}
^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.* The name=value pairs can be used elsewhere as needed.
=^author{Joe Blow}, ^date{March 1, 2021}, etc.
Joe Blow, March 1, 2021, etc.
Use a comment (see above) to completely hide metadata.
='^permalink{https://mdpaths.com/rrr/} ^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.
[1] This is the first reference.
[2] This is a second longer reference. Use the reference link *[2]* below to access it from anywhere in this document.
99 This is a non-reference item just to show you can mix and match.
[3] This is the third reference. It is linked to from an image.
[Author2008] Author/Year is a popular style used mostly in academic papers.
[Author2008a] Different article by the same author in the same year.
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 ()
Surround text with stars * for emphasis.
=You should *not* do that.
You should *not* do that.
## Inline Quotes ()
Surround text with double quotes.
=Everyone should read "Walden" by Thoreau.
Everyone should read "Walden" by Thoreau.
## Highlighting/Redlining (, )
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 #SocialMedia 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 #WordBoundary.
These hashtags are equivalent: #WordBoundary, #wordBoundary, #word_boundary.
Note that outside this context underscores '_' have no special meaning.
------------------------------
# Action Journaling (AJ)
I developed this ^todo list/journaling format(https://mdpaths.com/rrr/projects/action_journaling/index.html) in 2016.
AJ items are formatted as an unordered list.
White space after first char is ignored for readability.
=!! AJ Item Examples
=. open task (.)
=! open priority task (!)
=? open query/decision task (?)
=~ completed task (~)
=| deferred/reassigned task (|)
!! 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 #UTF8 order.
------------------------------
# My History of Textual Tinkering
1988 ^HYTEXT{../../hypertext_before_the_web/index.html} Hypertext Publishing System for MS-DOS
1989 Conversion of Medical Textbooks with ^AWK{https://richard.mdpaths.com/projects/kist/kist_guide/kist_images/kist-awk-book.jpg} (NLM Fellowship)
1996 ^MTX{mtx-format.text} Marked TeXt for Web Publishing (U of Fla)
1997 Self-Organizing Hypertext Notebooks (^Jrju{../../../medicine/medinfo/self_organizing_hypertext_notebooks/index.html})
2000s ^Action Journaling{https://mdpaths.com/rrr/projects/action_journaling/index.html} for Paper, Computer & Web
2016 ^TableTop{https://richard.mdpaths.com/projects/kist/kist_guide/kist_images/kist-tabletop.png} – Table Manipulation App
2020 Keep It Simple Text (^KIST{../index.html})
------------------------------
# Oddments/Bugs/Gotchas
The first non-blank line must be the document title.
Exceptions are ^-x switches(kist-html.html) and banner images.
The first cell in a table row *cannot be blank*.
Block quote nesting is not supported.
Captions for ordered lists are not supported.
Certain symbols have special meaning:
permalink -> metadata permanent address (URL)
temp -> use file name for image caption
'-sm' image suffix -> link to larger image
The source file must end with a newline.
^Endnote
[4] This is an endnote.
- ,
- .
Use \ chars when you cannot type tabs (web forms).
Add space for clarity with a tab followed by a period.
The number of tabs determines nesting.
It is up to the author to nest these properly!
## Simple List Example
tree
apple
pencil
## List Title Example
A single leading ^ after first
indicates a title. = ^List of Fruit = apple = banana = orange ^List of Fruit apple banana orange ## Ordered List Example A single leading # after first indicates an ordered list - .
= #Lorem ipsum dolor... etc.
#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.
.
Integer a eros vitae felis scelerisque gravida.
.
Cras orci justo, porttitor ut, suscipit et, ornare ut, velit. Proin orci tellus, pulvinar eu, consectetuer ut, faucibus vitae, tellus.
## Nested List Example
#one
two
abc
#uno
dos
left
right
tres
def
ghi
#up
down
three
jkl
# Preformatted Text (
) Lines beginning with equals signs = are passed through "as is" with no additional formatting. Note that long lines will 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 Direct use of *tab-separated values* (".tsv" or ".tab" files). It is up to the author to ensure data consistency! First char must *not* be a tab (indicating a list item). A leading ^ char on the first line indicates column headings. As with lists, \ chars may be used when tabs cannot be typed. ## 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 extra quotations (>>, >>>, etc.) are ignored. =>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 (
) Line begins with at least three dashes. =--- text is ignored, can be used as a comment --- text is ignored # Text Level Markup These elements occur *within* paragraphs, lists, etc. and *cannot span lines*. = Hypertext Links = = Images= = Metadata = = Word Level Styles , ,
, etc. # Name=Value Elements =^name{value} Also referred to as a "key/value" pair. Used for links, images, and metadata. This construct cannot span lines. *Staring with v0.19 the use of () is depreciated.* =^name(value) -> use ^name{value} instead! # Hypertext Links =Link to the ^Weather Forecast{https://forecast.weather.gov/}. Link to the ^Weather Forecast{https://forecast.weather.gov/}. =Link to ^Local File{kist-guide.txt} in the same directory. Link to a ^Local File{kist-guide.txt} in the same directory. Valid local file extensions are: *html htm txt text pdf* =Link to a ^Section{#s3} in the same document. Link to a ^Section{#s3} in the same document. *Non-local images* will be linked but not embedded. =Link to ^Remote Image{https://mdpaths.com/...jpg}. Link to ^Remote Image{https://mdpaths.com/rrr/blis_media/banner-river-pano.jpg}. # Images *Inline* images behave like paragraphs and will adjust to the size of the screen. *Floating* images will appear smaller, embedded within a paragraph. *Banner* images are a special case and appear above all other markup. See the top of this document for an example. Use *relative URLs* for local images (eg, "images/picture.jpg"). "#Alt_Text" should be a *short description* of the image. The magic word "temp" will default alt text to the file name. Valid image file extensions are: *jpg jpeg gif png* ## 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{kist_images/picture.jpg} 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]{kist_images/picture2.jpg} An image with no #alt_text is an error. ^{kist_images/picture2.jpg} You should instead use the "temp" placeholder as a way to quickly add an image without specific alt text. =^temp{kist_images/picture2.jpg} ^temp{kist_images/picture2.jpg} It is often useful to have a *smaller inline image* linked to its *full-sized* version. 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 create a link to it. You *cannot* have reference and image links in the same element. '### come back to the above statement, is it still true?? ### =^Small Image with Link{kist_images/picture4-sm.jpg} ^Small Image with Link{kist_images/picture4-sm.jpg} 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{kist_images/picture2.jpg} > >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{kist_images/carl_sagan_1994_float.png} *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. Galleries use the same general rules for images, formats, etc. Each gallery has a *title* and a *relative URL* to a directory. Each gallery image has a hypertext link to its full-sized original. There can be *multiple galleries* on a single page. It is assumed the gallery directory contains *only* image files. Caption text is cleaned up for clarity (capitalized, punctuation removed). For example... = ^Rock Art Gallery{kist_gallery/} ^Rock Art Gallery{kist_gallery/} ## Impromptu Slide Shows #Click on any image to view the first "slide". The full-sized image appears in a pop-up window. *Click anywhere on the image* to go to the next "slide". Click anywhere outside of the image to end the show. # Embedded Video & Audio Use the "kind=media" 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} ^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 MP4 File{video=kist_media/kayak-sailing.mp4} ## Local MP3 File =^Local MP3 File{audio=kist_media/purple-martins.mp3} ^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.* The name=value pairs can be used elsewhere as needed. =^author{Joe Blow}, ^date{March 1, 2021}, etc. Joe Blow, March 1, 2021, etc. Use a comment (see above) to completely hide metadata. ='^permalink{https://mdpaths.com/rrr/} ^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. [1] This is the first reference. [2] This is a second longer reference. Use the reference link *[2]* below to access it from anywhere in this document. 99 This is a non-reference item just to show you can mix and match. [3] This is the third reference. It is linked to from an image. [Author2008] Author/Year is a popular style used mostly in academic papers. [Author2008a] Different article by the same author in the same year. 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 () Surround text with stars * for emphasis. =You should *not* do that. You should *not* do that. ## Inline Quotes () Surround text with double quotes. =Everyone should read "Walden" by Thoreau. Everyone should read "Walden" by Thoreau. ## Highlighting/Redlining (,
) 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 #SocialMedia 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 #WordBoundary. These hashtags are equivalent: #WordBoundary, #wordBoundary, #word_boundary. Note that outside this context underscores '_' have no special meaning. ------------------------------ # Action Journaling (AJ) I developed this ^todo list/journaling format(https://mdpaths.com/rrr/projects/action_journaling/index.html) in 2016. AJ items are formatted as an unordered list. White space after first char is ignored for readability. =!! AJ Item Examples =. open task (.) =! open priority task (!) =? open query/decision task (?) =~ completed task (~) =| deferred/reassigned task (|) !! 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 #UTF8 order. ------------------------------ # My History of Textual Tinkering 1988 ^HYTEXT{../../hypertext_before_the_web/index.html} Hypertext Publishing System for MS-DOS 1989 Conversion of Medical Textbooks with ^AWK{https://richard.mdpaths.com/projects/kist/kist_guide/kist_images/kist-awk-book.jpg} (NLM Fellowship) 1996 ^MTX{mtx-format.text} Marked TeXt for Web Publishing (U of Fla) 1997 Self-Organizing Hypertext Notebooks (^Jrju{../../../medicine/medinfo/self_organizing_hypertext_notebooks/index.html}) 2000s ^Action Journaling{https://mdpaths.com/rrr/projects/action_journaling/index.html} for Paper, Computer & Web 2016 ^TableTop{https://richard.mdpaths.com/projects/kist/kist_guide/kist_images/kist-tabletop.png} – Table Manipulation App 2020 Keep It Simple Text (^KIST{../index.html}) ------------------------------ # Oddments/Bugs/Gotchas The first non-blank line must be the document title. Exceptions are ^-x switches(kist-html.html) and banner images. The first cell in a table row *cannot be blank*. Block quote nesting is not supported. Captions for ordered lists are not supported. Certain symbols have special meaning: permalink -> metadata permanent address (URL) temp -> use file name for image caption '-sm' image suffix -> link to larger image The source file must end with a newline. ^Endnote [4] This is an endnote.
- )
Lists are unordered
- by default.
A *leading tab* indicates a list item