``
title: IDK Documentation
last_modification_date: 2024/10/13
creation_date: 2024/10/13
output_path: "idk/idk_documentation.html"
summary: IDK markup documentation, which describe how to use it.
related: "idk/idk_todos.idk"(IDK's todos)
related: "idk/idk_goals.idk"(IDK's goals)
related: "idk/idk_readme.idk"(IDK's readme)
related: "idk/idk_technical.idk"(IDK's technical)
category: "documentation;idk;"
_"idk_banner_800.jpg"(500x219, "simple banner for the article")
inside_index_menu: true
``
Get the program
The IDK parser is available following "idk/idk_readme.idk[#1]"(Quick use).
Raw files
All website's web page have this ~{<span class="icon icon-Pencil"></span>}~ you can click, permiting you to see the IDK page that created it.
Goals
For details about the goals of IDK markup go "idk/idk_goals.idk"(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/idk_todos.idk"(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 [#1](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:
a. URI : "https://a_wrong_http_url.com"(a wrong http url). `` `"https://a_wrong_http_url.com"(a wrong http url)` ``
. file : "wrong/file/path/wrong.txt"(a wrong file path). `` `"wrong/file/path/wrong.txt"(a wrong file path)` ``
. internal link on different IDK file: "softwares/softwares.idk[#100]"(wrong internal link). `` `"softwares/softwares.idk[#100]"(wrong internal link)` ``
Normal links
URI
This is a "https://axeldaguerre.com"(uri link). `` `"https://axeldaguerre.com"(uri link)` ``
File
This is a "idk_documentation/table_1.csv"(file link). `` `"idk_documentation/table_1.csv"(file link)` ``
Internal link on different IDK file
We can either mention "softwares/softwares.idk[#1]"(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: "https://axeldaguerre.com"(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_documentation_img_1.jpeg"(30x30, "from my town, Capbreton.") `` `_"idk_documentation_img_1.jpeg"(30x30, "from my town, Capbreton.")` ``
_"idk_documentation_img_1.jpeg"(350x200, "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
```
``
a. one
b. two
c. three
Numeric
``
```
1. one.
2. two.
3. three.
```
``
1. one.
2. two.
3. three.
Unordered
``
```
. one.
. two.
. 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.
//``
//```
//a. one.
// . two. (automatically derived from the first)
//1. one.
// . two. (automatically derived from the first)
//```
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.
```
``
i. first alpha.
1. first numeric 1.
. second numeric 2.
. first unordered.
. second unordered.
. second alpha.
. 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.
```
The text will keep all
its // comment are not displayed.
whitespace.
We are able to write potential clashing tokens like this <button>button</button> displayed inside HTML document.
```
`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 [#4]).
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{}` |
|--------------------------------------------------------------------------------------------------|
```
``
|==================================================================================================|
| Feature | IDK [x] | HTML | Markdown | XML | LaTeX |
|==================================================================================================|
| Readability | High | Medium [#8]_ | 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 | | |
```
``
| 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 [#4]_
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
;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;
From files
``
```
_"idk_documentation/table_1.csv" _"idk_documentation/table_2.csv"
```
``
_"idk_documentation/table_1.csv" _"idk_documentation/table_2.csv"
Tips
1. table does not required to have aligned cells.
. cells can be on more than one line.
. row separation on non-CSV tables can be either blank line or separated by at least one triple hyphen `---`.
. We can select columns by using the checkbox `[x]`.
. The first token `|` or `;` make the table start.
. Then other first/last `|` or `;` can be ommited.
. The end of a table (new line or separation line) can be ommited.
. CSV tables can't span a row on multiple lines.
. CSV must start `;` on new table's first line when not used with files but directly written (as seen on above example).
. All table types can have rows separated by blank lines for readability.
. Side by side tables must have their rows aligned.
. 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 [#1]_
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 2
paragraph
Heading 3
paragraph
Heading 4
paragraph
Heading 5
paragraph
``
Context is available inlined too:
This is a text in which we append a context ``creation_date: 2023/11/13 | this is a text | "https://axeldaguerre.com"(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.
>
| ``
| author: Author A
| author_link: https://axeldaguerre.com
| remark: I am not conviced by this but will think deeper.
| creation_date: 2024/09/01
| ``
| The wrong answer is throwing away your career to do _something_ with the elephant, like running a circus. The elephant is a distraction as you are a professional software developer focusing on your career. Your skill set is much better used for writing code. It's a trap question.
< ``
| author: Author A
| author_link: https:axeldaguerre.com
| ``
| _There is no right or wrong answer_ for such a ridiculous question.
| It's just a matter whether you'll manage to read the mind of the employer and answer it the way he/she wants you to answer.
|
< ``
| author: Author B
| author_link: https:axeldaguerre.com
| ``
| Indeed, so it just adds random noise to the selection process.
|
<
|``
| author: Author C
| author_link: https:axeldaguerre.com
|``
|Jerky interview questions weed out people who lose their temper, have a bad attitude,
|or otherwise lack the grace to respond in an appropriate way when taken off script. This won't help you find the best candidate, but it will help you eliminate a lot of terrible ones.
<``
| author: Author A
| author_link: https:axeldaguerre.com
|``
| Elephant burgers!
`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 [#1] is available inside each quotes.
---------------------------------
Footnotes [#2]_
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 [*1]. 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.
[*1] then later we provide further informations to the previous chunk of text.
Internal links [#3]_
They permit to reference a link inside the same document. It goes this way: we reference here [#1], you can add descriptive link by appending () to it like [#4](CSV table).
We allow to have link inside regular text [#2] and on title [#1] or inside a table cell [#8].
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 [x] or []
---
Raw text
Sometimes you want to write pure text which potentially can be interpreted by a program, like HTML parser.
~{<button>Click 1</button>}~
~{<button>click 2</button>}~You can do it inlined too : ~{<button>click 3</button>}~
Extra features
If a footnote [#2] or an internal link [#3] 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.