(zettel (meta (back "00001007000000") (backward "00001007000000") (box-number "1") (created "00010101000000") (forward "00001007030000 00001007030200 00001007030300 00001007031000 00001007040000 00001007040310 00001007040330 00001007040340 00001007050000") (modified "20211124175047") (published "20211124175047") (role "manual") (syntax "zmk") (tags "#manual #zettelmarkup #zettelstore") (title "Zettelmarkup: General Principles")) (rights 4) (encoding "") (content "Any document can be thought as a sequence of paragraphs and other [[block-structured elements|00001007030000]] (\"\"blocks\"\"), such as [[headings|00001007030300]], [[lists|00001007030200]], quotations, and code blocks.\nSome of these blocks can contain other blocks, for example lists may contain other lists or paragraphs.\nOther blocks contain [[inline-structured elements|00001007040000]] (\"\"inlines\"\"), such as text, [[links|00001007040310]], emphasized text, and images.\n\nWith the exception of lists and tables, the markup for blocks always begins at the first position of a line with three or more identical characters.\nList blocks also begin at the first position of a line, but may need one or more identical character, plus a space character.\n[[Table blocks|00001007031000]] begin at the first position of a line with the character \"\"``|``\"\".\nNon-list blocks are either fully specified on that line or they span multiple lines and are delimited with the same three or more character.\nIt depends on the block kind, whether blocks are specified on one line or on at least two lines.\n\nIf a line does not begin with an explicit block element. the line is treated as a (implicit) paragraph block element that contains inline elements.\nThis paragraph ends when a block element is detected at the beginning of a next line or when an empty line occurs.\nSome blocks may also contain inline elements, e.g. a heading.\n\nInline elements mostly begins with two non-space, often identical characters.\nWith some exceptions, two identical non-space characters begins a formatting range that is ended with the same two characters.\n\nExceptions are: links, images, edits, comments, and both the \"\"en-dash\"\" and the \"\"horizontal ellipsis\"\".\nA link is given with ``[[...]]``{=zmk}, an images with ``{{...}}``{=zmk}, and an edit formatting with ``((...))``{=zmk}.\nAn inline comment, beginning with the sequence ``%%``{=zmk}, always ends at the end of the line where it begins.\nThe \"\"en-dash\"\" (\"\"--\"\") is specified as ``--``{=zmk}, the \"\"horizontal ellipsis\"\" (\"\"...\"\") as ``...``{=zmk}[^If put at the end of non-space text.].\n\nSome inline elements do not follow the rule of two identical character, especially to specify [[footnotes|00001007040330]], [[citation keys|00001007040340]], and local marks.\nThese elements begin with one opening square bracket (\"\"``[``\"\"), use a character for specifying the kind of the inline, typically allow to specify some content, and end with one closing square bracket (\"\"``]``\"\").\n\nOne inline element that does not begin with two characters is the \"\"entity\"\".\nIt allows to specify any Unicode character.\nThe specification of that character is put between an ampersand character and a semicolon: ``&...;``{=zmk}.\nFor example, an \"\"n-dash\"\" could also be specified as ``–``{==zmk}.\n\nThe backslash character (\"\"``\\\\``\"\") possibly gives the next character a special meaning.\nThis allows to resolve some left ambiguities.\nFor example, a list of depth 2 will begin a line with ``** Item 2.2``{=zmk}.\nAn inline element to strongly emphasize some text begin with a space will be specified as ``** Text**``{=zmk}.\nTo force the inline element formatting at the beginning of a line, ``**\\\\ Text**``{=zmk} should better be specified.\n\nMany block and inline elements can be refined by additional [[attributes|00001007050000]].\nAttributes resemble roughly HTML attributes and are put near the corresponding elements by using the syntax ``{...}``{=zmk}.\nOne example is to make space characters visible inside a inline literal element: ``1 + 2 = 3``{-} was specified by using the default attribute: ``\\`\\`1 + 2 = 3\\`\\`{-}``.\n\nTo summarize:\n\n* With some exceptions, blocks-structural elements begins at the for position of a line with three identical characters.\n* The most important exception to this rule is the specification of lists.\n* If no block element is found, a paragraph with inline elements is assumed.\n* With some exceptions, inline-structural elements begins with two characters, quite often the same two characters.\n* The most important exceptions are links.\n* The backslash character can help to resolve possible ambiguities.\n* Attributes refine some block and inline elements.\n* Block elements have a higher priority than inline elements.\n\nThese principles makes automatic recognizing zettelmarkup an (relatively) easy task.\nBy looking at the reference implementation, a moderately skilled software developer should be able to create a appropriate software in a different programming language."))