diff options
Diffstat (limited to 'posts/markdown-examples.md')
| -rw-r--r-- | posts/markdown-examples.md | 254 |
1 files changed, 254 insertions, 0 deletions
diff --git a/posts/markdown-examples.md b/posts/markdown-examples.md new file mode 100644 index 0000000..dc3d2dc --- /dev/null +++ b/posts/markdown-examples.md @@ -0,0 +1,254 @@ +# Markdown Examples in barf + +2023-01-05 + +This following was lifted from [https://github.com/karlb/smu](https://github.com/karlb/smu) + +`smu` Syntax +============ + +smu was started as a rewrite of +[markdown](http://daringfireball.net/projects/markdown/) but became something +more lightweight and consistent. It differs from [CommonMark](https://commonmark.org/) in the following ways: + +* No support for _reference style links_ +* Stricter indentation rules for lists +* Lists don't end paragraphs by themselves (blank line needed) +* Horizontal rules (`<hr>`) must use `- - -` as syntax +* Code fences have stricter syntax + +Patches that increase the CommonMark compatibility are welcome as long as they don't increase the code complexity significantly. + +This project is a fork of the [original smu](https://github.com/gottox/smu) by +[Enno Boland (gottox)](https://eboland.de). The main differences to the +original smu are: + +* Support for code fences +* Improved [CommonMark](https://commonmark.org/) compatibility. E.g. + * Code blocks need four spaces indentation instead of three + * Skip empty lines at end of code blocks + * Ignore single spaces around code spans + * Keep HTML comments in output + * Improved spec compliance for lists + * Nesting code block in blockquotes works + * "Empty" lines in lists behave identically, no matter how much whitespace they contain + * No backslash escapes in code blocks + * Use first number as start number for ordered lists +* Added a simple test suite to check for compliance and avoid regressions + +Inline patterns +--------------- + +There are several patterns you can use to highlight your text: + +* Emphasis + * Surround your text with `*` or `_` to get *emphasised* text: + This *is* cool. + This _is_ cool, too. + * Surround your text with `**` or `__` to get **strong** text: + This **is** cool. + This __is__ cool, too. + * Surround your text with `***` or `___` to get ***strong and emphasised*** text: + This ***is*** cool. + This ___is___ cool, too. + * But this example won't work as expected: + ***Hello** you* + This is a wontfix bug because it would make the source too complex. + Use this instead: + ***Hello*** *you* + +* inline Code + + You can produce inline code by surrounding it with backticks. + + Use `rm -rf /` if you're a N00b. + Use ``rm -rf /`` if you're a N00b. + Use ```rm -rf /``` if you're a N00b. + + Double and triple backticks can be used if the code itself contains backticks. + + +Titles +------ + +Creating titles in smu is very easy. There are two different syntax styles. The +first is underlining with at least three characters: + + Heading + ======= + + Topic + ----- + +This is very intuitive and self explaining. The resulting sourcecode looks like +this: + + <h1>Heading</h1> + <h2>Topic</h2> + +Use the following prefixes if you don't like underlining: + + # h1 + ## h2 + ### h3 + #### h4 + ##### h5 + ###### h6 + +Links +----- + +The simplest way to define a link is with simple `<>`. + + <http://s01.de> + +You can do the same for E-Mail addresses: + + <yourname@s01.de> + +If you want to define a label for the url, you have to use a different syntax + + [smu - simple mark up](http://s01.de/~gottox/index.cgi/proj_smu) + +The resulting HTML-Code + + <a href="http://s01.de/~gottox/index.cgi/proj_smu">smu - simple mark up</a></p> + +Lists +----- + +Defining lists is very straightforward: + + * Item 1 + * Item 2 + * Item 3 + +Result: + + <ul> + <li>Item 1</li> + <li>Item 2</li> + <li>Item 3</li> + </ul> + +Defining ordered lists is also very easy: + + 1. Item 1 + 2. Item 2 + 3. Item 3 + +Only the first number in a list is meaningful. All following list items are +continously counted. If you want a list starting at 2, you could write: + + 2. Item 1 + 2. Item 2 + 2. Item 3 + +and get the following HTML which will render with the numbers 2, 3, 4: + + <ol start="2"> + <li>Item 1</li> + <li>Item 2</li> + <li>Item 3</li> + </ol> + +Code & Blockquote +----------------- + +Use the `> ` as a line prefix for defining blockquotes. Blockquotes are +interpreted as well. This makes it possible to embed links, headings and even +other quotes into a quote: + + > Hello + > This is a quote with a [link](http://s01.de/~gottox) + +Result: + <blockquote><p> + Hello + This is a quote with a <a href="http://s01.de/~gottox">link</a></p> + </blockquote> + + +You can define a code block with a leading Tab or with __4__ leading spaces + + this.is(code) + + this.is(code, too) + +Result: + <pre><code>this.is(code)</code></pre> + <pre><code>this.is(code, too) + </code></pre> + +Please note that you can't use HTML or smu syntax in a code block. + +Another way to write code blocks is to use code fences: + + ```json + {"some": "code"} + ``` + +This has two advantages: +* The optional language identifier will be turned into a `language-` class name +* You can keep the original indentation which helps when doing copy & paste + +Tables +------ + +Tables can be generated with the following syntax: + + | Heading1 | Heading2 | + | -------- | -------- | + | Cell 1 | Cell2 | + +Aligning the columns make the input nicer to read, but is not necessary to get +correct table output. You could just write + + | Heading1 | Heading2 | + | --- | --- | + | Cell 1 | Cell2 | + +To align the content of table cells, use `|:--|` for left, `|--:|` for right +and `|:--:|` for centered alignment in the row which separates the header from +the table body. + + | Heading1 | Heading2 | Heading3 | + | :------- | :------: | -------: | + | Left | Center | Right | + +Other interesting stuff +----------------------- + +* to insert a horizontal rule simple add `- - -` into an empty line: + + Hello + - - - + Hello2 + + Result: + <p> + Hello + <hr /> + + Hello2</p> + +* Any ASCII punctuation character may escaped by precedeing them with a + backslash to avoid them being interpreted: + + !"#$%&'()*+,-./:;<=>?@[]^_`{|}~\ + +* To force a linebreak simple add two spaces to the end of the line: + + No linebreak + here. + But here is + one. + +embed HTML +---------- + +You can include arbitrary HTML code in your documents. The HTML will be +passed through to the resulting document without modification. This is a good +way to work around features that are missing in smu. If you don't want this +behaviour, use the `-n` flag when executing smu to stricly escape the HTML +tags. |