mharkup example an example document which explains and documents the features of mharkup. # motivation mharkup is a weird markup language to get around things that annoy me in most markdown flavors. ## goals as someone using mharkup, you ` can read and write it in your text editor ` can export and `/printable(print) it ` can easily (re)organize your document ` probably won't apply formatting on accident `/backtick() # the format ## documents documents are split into sections. the first section is always the document's title. sections are separated by an empty line. for example, here are the sections you just read: [[ #!mharkup ## documents documents are split into sections. the first section is always the document's title. sections are separated by an empty line. for example, here are the sections you just read: `()#!mharkup ## documents ... ]] each mharkup file starts with a title, the first line of the file, which doesn't have any leading hashtags. a file `+(should) also have a small description of what it will contain, and the file's actual content `+(should) be in subdocuments. for example, here's how this file starts: [[ #!mharkup mharkup example an example document which explains and documents the features of mharkup. # motivation ... ]] ## sections in most cases, a section is just a few lines of text. you've probably already noticed that linebreaks are usually ignored `-(or, more accurately, replaced with spaces). sections beginning with a hashtag (#) are special. the first line specifies the type of section you want, and the other lines are the section's content. you've already seen this with #!mharkup in the first example. the types of sections you can create like this are: ` #@ quotes ` #! code blocks ` #\ various extensions ### backticks /here in a section, you can use the backtick (``) to apply text formatting, or you can start a section with a backtick followed by a space to create a list. here's a list of things the backtick can do: ` create a list ` represent itself ``: ```` ` add a `-(note): ``-(note) ` mark something that's `~(wrong): ``~(wrong) ` highlight a `_(special) element: ``_(special) ` add emphasis to `+(something): ``+(something) ` highlight something `*(important): ``*(important) ` insert raw `{`text`}: `<`{`text`}>: `2{`<`{`text`}>}}: `2<`2{`<`{`text`}>}}>>: ... ` link `/here(somewhere): ``/here(somewhere) ` use an extension: ``\spec{...} or ``\spec<...> ` combine any of these: `*_+(whoah): ``*_+(whoah) ## you can also insert a subdocument by inserting a new title section. for example, the backticks subdocument starts with the following section: #!mharkup ### backticks /here and these sections are back in the outer document, at depth 2 instead of 3, because of an empty title section: #!mharkup ## since sections are separated by an empty line, they don't usually contain empty lines themselves. however, they absolutely can, and for code blocks, you will definitely need it quite quickly. in normal text, where newlines are usually removed, an empty line can be used to force a linebreak. to add an empty line to a section, enclose it in at least one set of square brackets. `-(for the following example, to be able to include the double brackets, the #!mharkup section is enclosed in 3 more sets of square brackets.) [[[ #!mharkup [[ #@mark and that's all, i think... ]] ]]] [[ #@mark and that's all, i think... ]] the following subdocuments just show how to use the different section types in more detail. ### quotes #@mark @21st century i've solved many problems that noone's ever had. in this case, the first line of the section was #@mark @21st century. ### code #!python def do_something_productive(): pass in this case, the first line of the section was #!python. ### extensions #!mharkup #\texm \sum_{a=0}^{20} a^2 #\texm \sum_{a=0}^{20} a^2 #!mharkup or inline: `{`\texm} `<`2\texm{ \frac{1}{2} }}> or inline: `\texm or `2\texm{ \frac{1}{2} }} #!mharkup #\html deprecated, but funny #\html deprecated, but funny # reasoning ## why is text formatting so inconvenient? /backtick i really don't want to think about how many special characters i can't use while writing my plaintext documents. i know that writing `<`*(word)> instead of **word** is inconvenient, but using *, _, and even \ without any escaping may `-[(?)] already be worth it. Also, * and _ can't be nested, so if you took `+(this **cool** section) and copy-pasted it into an already bold section, you would get `+(**this **cool** section**) which is just... ew. Meanwhile `{`*(this `*(cool) section)} works just fine and produces `*(this `*(cool) section). ## why does it need to be printable? /printable i don't expect to ever print out one of these documents, but i want them to be exportable to a static format, one where the user can read every piece of information in the document without having to interact with their device. this requirement just happens to line up with printability :) ## why don't the titles get smaller? /titlesize so that you can have as many layers of document as you want without asking yourself "is that just text in a

or is it a really small heading?", and so that you can move subdocuments between layers without having to think about it. to illustrate this, see how

and look in your browser: #\html this is a paragraph

followed by a h7, the smallest heading

[ crazy, right? and i actually lied. the "paragraph" is a and the "h7" is a

element :) and here's 10 layers of documents in mharkup: ] ########## whoah, that's a lot but it's still perfectly readable ## why are there no nested lists? /listnesting the real answer is, implementing it was hard and it didn't feel natural with the rest of the syntax. another answer is, if you have enough content to require nested lists, you should just use subdocuments. this will also force you to have good titles for each element. it's sometimes unclear if you should use nested lists or headings in a markdown document, and my own .md notes are inconsistent in this way. and when i did use a nested list, some elements were like titles for the inner list, and others had their own content and then still contained another list. it's an inconsistent mess, so not having it in mharkup isn't too upsetting for me `-[(yet..., i'm a big fan of lists in .md)].