Skip to content

Latest commit

 

History

History
171 lines (106 loc) · 5.11 KB

extras.md

File metadata and controls

171 lines (106 loc) · 5.11 KB
Raw

Extras

Note: This is all very experimental.

A Bismark editor should clearly show which extra features it supports. Either within its toolbar or in a popover.

For example:

Basic Bismark
+ Inline Styles: Highlight, Superscript, Subscript
+ References: Citations, Notes
+ Comments
+ Extensions: Image, Table, TeX
+ Syntax Highlighting: JavaScript, Clojure, Rebol
+ Inline Code: JavaScript
+ Code Blocks: JavaScript, Clojure

Some examples on this page require certain Markdown extensions to render correctly.

Inline Styles

Inline styles (bold, italic and verbatim) may be extended with additional styles from a predetermined set.

==highlighted==
~~redacted~~
++inserted++
^superscript^
~subscript~

highlighted
redacted
inserted
superscript
subscript

References

A reference is a key enclosed in square brackets […] that matches a definition.

<According to Wikipedia [wiki en SQL]>, [?SQL] was originally called SEQUEL.[^1][*a]

According to Wikipedia, SQL was originally called SEQUEL.12

Definitions

Definitions have the syntax [key]: value and are referenced using [key].

Definitions are used for abbreviations, citations, notes and snippets.

If the key starts with a ?, it's an abbreviation.
If the key starts with a ^, it's a citation.
If the key starts with a *, it's a note.
Otherwise, it's a snippet/template.

A snippet becomes a template if one or more variable names are specified in curly brackets {…} after the key, separated by space. A variable name suffixed by ... gobbles up all text, including whitespace, until ] is encountered. Variable names are referenced within the template using curly brackets {…}.

The key and any variables are case insensitive and can't start with - or contain spaces, [ or ].

[*] is a valid note reference, as is [**], [***], etc.

[?SQL]: Structured Query Language
[^1]: D.D. Chamberlin, <Oral history interview with Donald D. Chamberlin https://hdl.handle.net/11299/107215> (Charles Babbage Institute, 2001).
[*a]: In fact, many still pronounce it "sequel".
[wiki {lang} {title...}]: http://{lang}.wikipedia.org/wiki/{title}

Definitions take precedence over extensions.

Comments

Comments are enclosed in square brackets that start with and optionally end with -.

[- A comment for future reference -]

[-
This is a _block_ comment.
-]

Uses cases include:

  • Notes to self
  • Placeholders
  • Corrections
  • Exclusion from output

Extensions

Bismark renderers can be extended by sub-renderers to provide additonal features.

Enclosing a section of text in square brackets […] prefixed with the name of an extension, will cause it to be rendered by that extension.

Which renderers are supported depend on the environment. If a renderer is not supported, the contents should be rendered as usual. Note how the image will fall back to a link in the first example.

Examples

An image within a spoiler alert:

[spoiler
  [image <A happy little quokka holding a twig https://i.imgur.com/KLsmqqR.jpeg>]
]
Spoiler

Tables, using Markdown's table syntax:

[table
| Bismark    | Markdown                |
| ---------- | ----------------------- |
| `*bold*`   | `**bold**` / `__bold__` |
| `_italic_` | `*italic*` / `_italic_` |
]
Bismark Markdown
*bold* **bold** / __bold__
_italic_ *italic* / _italic_

Math formulas, assuming the environment supports TeX:

[tex \dfrac{\partial y}{\partial x} = x ]

$$ \dfrac{\partial y}{\partial x} = x $$

Markdown inside Bismark:

Because [md *why not!* ]

Because why not!

Syntax Highlighting

Verbatim blocks may be syntax highlighted by specifying a supported language.

```rebol
print "Hello, world!"
```

print "Hello, world!"

Inline Code

Code enclosed in curly braces {…} will be evaluated inline when rendered.

The answer is... { 2 * 3 * 7 }!

Last updated: { Temporal.Now.plainDateTimeISO().toLocaleString('se') }

The answer is… 42!

Last updated: 2023-01-31 14:27:01

Only one language can be supported at a time, to be specified by the renderer. While this is not very portable, it could be a powerful feature within an environment.

Because { and } often occur in programming languages, parsers must track nested {…} to reach the closing } of the inline code element.

Footnotes

  1. D.D. Chamberlin, Oral history interview with Donald D. Chamberlin (Charles Babbage Institute, 2001). ↩

  2. In fact, many still pronounce it "sequel". ↩