IDK Documentation

Get the program

The IDK parser is available following Quick use.

Raw files

All website's web page have this you can click, permiting you to see the IDK page that created it.

Goals

For details about the goals of IDK markup go IDK's goals. In short it is designed to be easy to read, write and encode complex data.

Work In Progress

The markup is in active development and is still in alpha, check the IDK's todos to see what is coming and which bugs have to be fixed.

Availability

All the text components described below are available everywhere, only context have narower possibility (see Context section).

Headings

Whitespace count indentation determined the text block type.Heading 2 // none __paragraph // 2 ____Heading 3 // 4 ______paragraph // 6 ________Heading 4 // 8 __________paragraph // 10 ____________Heading 5 // 12 ______________paragraph // 14

Links

Valid/invalid

All local and uri links can be validated by the parser when asked, resulting on wrong link as below:

1. a.URI : a wrong http url. "https://a_wrong_http_url.com"(a wrong http url)
2. b.file : a wrong file path. "/wrong/file/path/wrong.txt"(a wrong file path)
3. c.internal link on different IDK file: wrong internal link. "/softwares/softwares.idk[#100]"(wrong internal link)

Normal links

URI

This is a uri link. "https://axeldaguerre.com"(uri link)

File

This is a file link. "/assets/files/idk_documentation/table_1.csv"(file link)

Internal link on different IDK file

We can either mention other idk file's internal link. "/softwares/softwares.idk[#1]"(other idk file's internal link)

Link's name

Setting a specific name for the file can be done that way: axeldaguerre.com

Image link

By prefixing a link with _ it can be displayed on the document, you can specify its dimension and a description: _"/idk/idk_documentation/idk_documentation_img_1.jpeg"(30x30, "from my town, Capbreton.")

Availability

Everywhere.

Text formating

Bold

A bold text. _bold text_

Italic

A italic text. __italic text__

Availability

Everywhere.

List

Block list is available using combinaison of . with combinaison of character, on new line.

Alpha a. one b. two c. three

1. a.one
2. b.two
3. c.three

Numeric1. one. 2. two. 3. three.

1. 1.one.
2. 2.two.
3. 3.three.

Unordered1. one. 2. two. 3. three.

• .one.
• .two.
• .three.

Automatic increment

When list are modified frequently it is convenient to only set the first item's ordering number and let the parser derived the following item's ordering number.

Complex list

There is no restriction on the number of sublist and list's items. We can either mix the three types of list available inside the entire list. Automatic ordering works there too.i. first alpha. 1. first numeric 1. . second numeric 2. . first unordered. . second unordered. . second alpha. . third alpha.

1. i.first alpha.
   1. 1.first numeric 1.
   2. 2.second numeric 2.
      • .first unordered.
      • .second unordered.
2. j.second alpha.
3. k.third alpha.

Inlined list

We can write inlined list as follow: 1.item one 2.item two 3.item three. 1. item one 2. item two 3. item three. (at least three bullets, either numeric OR alpha type).

Automatic list derivation

The markup will analyze the potential list, if only one item is written, it will set it as regular text.

Block text

A block text can be a plain text or data structured text. All the whitespace inside it is preserved.

Note: in the future, syntax highlighting will be possible on specific texts.

Escaping tokens

We are able to escape any reserved token by preceding it by "\". Like here: this is NOT _a bold text_. NOT \_a bold text\_

Tables

IDK allow to write tables which are understood internally, there are not just for display.

Side by side

All tables types allow to have multiple side tables. It process all tables that are right to the first one and set them as side tables (see below ⁴).

Types

Full

Best for readability.|==================================================================================================| | Feature | IDK [x] | HTML | Markdown | XML | LaTeX | |==================================================================================================| | Readability | High | Medium | High | Low | Low | |--------------------------------------------------------------------------------------------------| | Complexity | Low | High | Low | High | High | |--------------------------------------------------------------------------------------------------| | Use Case | Semantic/Data | Web | Docs | Data | Papers | |--------------------------------------------------------------------------------------------------| | Formatting | Limited | Full | Limited | None | Advanced | |------------------------------------------------------------ -------------------------------------| | Extensibility | Low | High | Low | High | High | |--------------------------------------------------------------------------------------------------| | Learning Curve | Easy | Steep | Easy | Steep | Steep | |--------------------------------------------------------------------------------------------------| | Bold | `_Bold_` | `<b>Bold</b>`| `**Bold**` | `<b></b>`| `\textbf{}` | |--------------------------------------------------------------------------------------------------| | Images | `_"your_link"()`| `<img>` | `![Alt]()` | `<img>` | `\includegraphics{}` | |--------------------------------------------------------------------------------------------------| | Lists | `. item` | `<ul><li>` | `- Item` | `<list>` | `\begin{itemize}` | |--------------------------------------------------------------------------------------------------| | Links | `"your_link"()` | `<a href="">`| `[Txt]()` | `<link>` | `\href{}` | |--------------------------------------------------------------------------------------------------|

Light

Short but not the best for readability.| Feature | IDK [x] | Markdown | | Bold | `_Bold_` | `**Bold**` | | Italic | `__Bold__` | `*Italic*` | | link | `"link.com"` or `"link.com"(link)` | `[text](link.com)` | | Heading | derived from indentation | use of `#` | | Image | `"image_link.jpg"` or `"image_link.jpg"(image properties)` | `` | | List | use of `.`, `a.`, `1.` | use of `-`, `a.`, `1.` | | Block | ` \```block text\``` ` | ` \```block text\``` ` | | Footnote | `[*1]` without indentation. | `[^1]:` | | Footnote's | `[*1]` inside a text. | `[^1]` inside a text. | | reference | | | | Internal | `text [#1]_` | `text {#1}` | | link | | | | Internal | `[#1]` or `[#1](link name)` | `[link name](#1)` | | link's | | | | reference | | |

CSV

File format used almost everywhere, great to work with files and tools producing them. ;Feature; IDK [x]; Pandoc; ;Feature; IDK [x]; Pandoc; inlined list; yes; no; side by side table; yes; no; table's cell selection; yes; no; link checker; yes; no; HTML conversion; yes; yes; discussion; yes; no; context; yes; no; table's row on multiple lines; all types except CSV; grid tables only;

Directly

From files_"/assets/files/idk_documentation/table_1.csv" _"/assets/files/idk_documentation/table_2.csv"

Tips

1. 1.table does not required to have aligned cells.
2. 2.cells can be on more than one line.
3. 3.row separation on non-CSV tables can be either blank line or separated by at least one triple hyphen ---.
4. 4.We can select columns by using the checkbox [x].
5. 5.The first token | or ; make the table start.
6. 6.Then other first/last | or ; can be ommited.
7. 7.The end of a table (new line or separation line) can be ommited.
8. 8.CSV tables can't span a row on multiple lines.
9. 9.CSV must start ; on new table's first line when not used with files but directly written (as seen on above example).
10. 10.All table types can have rows separated by blank lines for readability.
11. 11.Side by side tables must have their rows aligned.
12. 12.internal links, footnote reference are available on table's cell.

Note: Table will be an important structure inside the markup, they will have extensive possibility and have real data types.

Context

A text's context is targeting the last text block, which is a paragraph or a heading. It will be visually appended at the end of it.

Context is a crucial part of IDK markup. It is a way to have a text which add details on the previous text written. It will not be a part of the text (not directly visible when you read the text). Instead, reader is able to interact in order to read it, which permit better readability. When converted to HTML, it means that a button is clickable that enable the reader to see it.

It is used to add details on how the previous text was written. Great for quick notes, writer is able to convey informations on the conditions it was written.Heading 2paragraphHeading 3paragraphHeading 4paragraphHeading 5paragraph

Context is available inlined too:

This is a text in which we append a context 2023/11/13 this is a text www.axeldaguerre.com.

Same stuff is available to it than normal context except text level (headings and paragraph), eveything is regular text. This is an unformated text hello unformated

Discussion threads

IDK permit to represent a discussion thread, it does understand it internally, it is not just for display.

By using combinations of > and < and indentation, a whole discussion can be represented.

NOTE: "<" does not have different meaning than ">", it is used for better readability if wanted. "|" are not mandatory and is used for readability too.

Context ¹ is available inside each quotes.

Footnotes

When we do not want to use context inlined because their make reading complicated when too long, we can use transcripts which does similar.

Let's say we write a text and we decide to append a ¹. This is not a regular footnote, because writer can append it anywhere in the document, but the function is the same, and keeps the same possibilibilities than context.

some text are written ...

Footnotes can be inside table's cell, table's column and text block.

Internal links

They permit to reference a link inside the same document. It goes this way: we reference here ¹, you can add descriptive link by appending () to it like CSV table.

We allow to have link inside regular text ² and on title ¹ or inside a table cell ⁸.

Because one of the IDK markup's goals is to be able to write text without fancy text editor, we want the link to be easily searchable when link reference is encountered, so we just add a _ to the link to differentiate them.

Internal links can be inside table's cell, table's column and text block.

Checkbox

Checkbox permit to set a component as checked on unckecked and have special meaning depending on the component on which it is appended. For example, on table's cell it will set the cell or the entire table's column as selected (see table's examples above). [x] and []

Displayed as or

Raw text

Sometimes you want to write pure text which potentially can be interpreted by a program, like HTML parser.

Click 1

click 2You can do it inlined too : click 3

Extra features

If a footnote ² or an internal link ³ reference does not have a matching definition, the link is set as broken and user is warned.

Avoid errors

Because one of the main goals is to be easy to write, the parse is consistenly trying to make assertions when it can. To name a few: like not having new line between text block and a table will end the table.

It always avoid critical error on ambigous document and will prefer warnings.

Use a bit of reading science

Science knows a lot about how humans read. Since 1960 scientific have made several studies which can help to enhance reading experience. The output formats (HTML currently) tries to use a bit of the well backed ones. Not more than ~66 Characters per line, font build for readability on digital devices, font size and more. Sometimes it feels wrong, but because we can't directly feel it without being a skilled reader, we should not rely on our senses about this subject.