Under active development

This blog is being built along with a blogging framework for the entire Conundrum ecosystem.

This is taking significantly more time than building a simple blogging website, but when this is complete in a couple months, all users will be able to publish their notes as a blog, independent of any specific service, including Fluster.

Conundrum Syntax

Embedded Docs

You can show embedded docs within any rendered note using the Docs? or Docs?? command on a line all by it's ow. It needs to start the line, and must contain no leading white space or surround text on the same line. This works for all component names, Docs , and a handful of other commands that are described in the Docs command

Docs? // Short docs
Docs?? // Long docs

Below is the output of Docs?

Documentation

Trigger Desc
Docs?? The one you probably want to remember. This will take you back here.
Markdown?? A quick markdown reference for those just getting started.
Jsx?? A quick jsx reference for those that are ready to take advantage of the 'x' in mdx.
Syntax?? A reference to Conundrum specific syntax.
Emoji?? A sample table of many of the emojis available in Conundrum.
Components?? A list of all available components.
Conundrum?? A few details about the Conundrum transpiler that drives Fluster. If you ever want to take your notes elsewhere, this free & open-source tool can convert everything back to regular markdown, plain text, and more!

Every component also has documentation, available at that component's name with the same ? syntax.

Component Property Models

Trigger Desc Used in
Sizable?? The core styling model, especially for container components. Card ,
Container ,
Admonition ,
etc..
Emphasis?? A list of boolean properties that can apply unique styles like info or important . Highlight ,
Underline ,
Admonition ,
...

Text

Titles
# My Big Heading
> Keep in mind, you can add a subtitle by sliding a blockquote to the line directly underneath a title.
## My smaller Heading
### My smaller Heading
#### My smaller Heading
##### My smaller Heading
###### My smaller Heading

My Big Heading

Keep in mind, you can add a subtitle by sliding a blockquote to the line directly underneath a title.

My smaller Heading

My smaller Heading

My smaller Heading

My smaller Heading
My smaller Heading
Styled Text

Styled text follows the same rules as markdown, with

- My _italic_ text
- My **bold** text
- My ***Bold and Italic*** text
- My ~~strikethrough~~ text
  • My italic text
  • My bold text
  • My Bold and Italic text
  • My strikethrough text

Math

block level math
$$ {#my-equation}
\Delta\phi
=
\frac{6\pi GM}
{a(1-e^2)c^2}
$$

The optional id allows me to reference it by number: <EqRef id="my-equation"/>
Δϕ=6πGMa(1−e2)c2 \Delta\phi = \frac{6\pi GM} {a(1-e^2)c^2}
1

The optional id allows me to reference it by number: 1

Code

The language is optional, but a complete list of supported languages can be found [here]()
Code Block
```python
import scipy.constants as spc
import numpy as np

v = np.linspace(0, spc.c, 1000)
gamma = 1 / np.sqrt(1 - v**2 / spc.c**2)
```
import scipy.constants as spc
import numpy as np

v = np.linspace(0, spc.c, 1000)
gamma = 1 / np.sqrt(1 - v**2 / spc.c**2)
inline code
My python codeblock: `v = np.linspace(0, spc.c, 1000){:python}`

My python codeblock: v = np.linspace(0, spc.c, 1000)

The last block inside of the brackets optionally specifies the language.

Layout

Lists

List items start with a - or a number, and can optionally contain a checkbox.


1. My List Item
2. My List Item
3. My List Item
  My item's description
4. My List Item
  1. My List Item
  2. My List Item
  3. My List Item
    My item's description
  4. My List Item

- My List Item
- My List Item
- My List Item
- My List Item
  • My List Item
  • My List Item
  • My List Item
  • My List Item

To continue a list item with an optional description, indent the following line by 2 spaces or 1 tab for every time the item is nested plus one. For example, if the item is not nested at all, use 2 spaces or 1 tab. If the item is nested once, use 4 spaces or 2 tabs, etc.

Checkboxes

- [ ] Checkbox
- [x] Checked Checkbox
- [?] Question Mark Checkbox
- [-] Dash Checkbox
- [!] Exclamation Checkbox
- [!] Item with a desciption
  The description comes following 2 spaces for every time the item is nested + 1, so 2 spaces if the item is not nested, 4 if it's nested once, etc..

  • Checkbox
  • Checked Checkbox
  • ? Question Mark Checkbox
  • Dash Checkbox
  • ! Exclamation Checkbox
  • !
    Item with a desciption

    The description comes following 2 spaces for every time the item is nested + 1, so 2 spaces if the item is not nested, 4 if it's nested once, etc..

Horizontal Rule
--- 
--- With content in the middle ---

With content in the middle

Components

One of the primary features that sets Conundrum apart from Markdown is the addition of components. Components are just pieces of UI that you can insert as one piece, and modify the output based on a set of properties. You can see a list of all available components via the Components?? documentation, and more details for any component using the same question mark syntax following the name of that component, for example: Card??

This is the output of Components?

Components

All components have provided snippets and documentation available via the ?? syntax.

Component Description
Admonition A card with a colored header that can be optionally foldable. Used to draw attention to important content.
Hl ,
Highlight
Highlight the background of text in a variety of colors.
Ul ,
Underline
Underline text in a variety of colors.
Card A subtle layout with a title, an optional subtitle and a body.
Container A simple, unstyled utility component that can be used to apply arbitrary styles to content.
Grid A responsive grid that allows for making sure your notes align well on any screen size.
Hr Almost identical to the normal markdown based horizontal rule (the --- syntax), but this can accept a 'content' property can be used to insert a label into the divider.
Hint Add some subtle, colored text to draw attention to smaller content.
Tab This component works uniquely inside of a Tabs provider.
Tabs Create a set of interchangable tabs.
EqRef Reference a note by it's inline index number without worrying about the structure of your note.
Emoji Embed emoji's either with the standard :smile: notation or with the sizable Emoji component.
Toc Embed a navigable table of contents component in your note
Quote Insert a quote from a significant person, book, or another source.
Image Insert an image and size it accordingly.
Color Great for UI & Design workflows, create and label colors or groups of colors either inline or block level.

And the Jsx? docs for more general component syntax:

Intro to Conundrum

If you've never written a line of code, don't worry, you don't have to learn much. Writing your own functions and combining them to make an entire application can be quite complicated, but simply calling functions is just as simple as mardown. In the end, the <MyComponent>...</MyComponent> syntax is just you calling a function. All you need to know is the name of the component, and what properties that components accepts.

Documented Properties
  • Strings
  • Booleans
  • Numbers
  • Arrays (lists)
  • Objects
Not Documented Yet
  • Functions
    • This is my main priority after the initial release of Fluster, integrating a complete scripting language that allows users to pass functions to plot components. This feature was present in the previous release of Fluster, but due to the migration away from Javascript it has not yet been reimplemented.

Components

Components are the core of jsx, and a fundamental reason of why the language is so popular. Jsx allows us to organize 'code' in a format that makes it incredibly easy to read, very unlike the traditional code that makes up the jsx components behind the scenes.

Fluster provides a growing list of components for you, and with snippets to help with each component, you'll rarely have to write a component by hand. That doesn't mean however that it's not beneficial to know how to edit them for the inevitable moment when you delete the wrong quotation mark or bracket. If you've written any programming language, or even if you haven't, this is not as big of an ask as it my seem. Let's get started.

The Basics

Remember: Each component includes a set of short and long documentation that can be accessed using the ? or ?? syntax, snippets to help with auto-completion, syntax highlighting within the editor, and some hopefully helpful error messages to help when you provide an incorrect property.

Here are the core pieces of information you need to know as it pertains to calling a jsx function.

  • Components will always start with a < and a capital letter.
  • Components can accept any number of properties. While components traditionally each have their own set of properties, Fluster bundles them into common, repeated models for familiarity, while some components still accept unique properties.
  • Children is a unique property, being wrapped between the component. This is a big part of what makes jsx so readable, as we insert regular mdx content inside of the component where that content will actually render.
    • If a component does accept children, it's opening tag is closed with a single > , if it does not accept children the component accepts a shorthand where the second tag is not needed at all, and the first tag can be closed with a /> .

Examples

This Card component accepts children , so we use the > closing bracket on the opening tag.

components.mdx
<Card title="My title" desc="My optional description">
This is my card's body.
</Card>

This Toc (table of contents) component does not accept any children, so we don't need the closing tag and we can write it as:

components.mdx
<Toc />

Strings

See these docs for a much more thorough explanation
  1. A string is just a fancy word for words and letters. Numbers can also be strings, which might be confusing, but Conundrum will catch that for you if you make that mistake.
  2. To create a string, just wrap the content in either single ' , double " , or a backtick "`" (top left of the keyboard.).
  3. Conundrum currently does not support line breaks inside of strings. This might sound paradoxical to experienced programmers, but remember... pretty much everywhere a string is accepted, more Conundrum content is accepted as well.
  4. Wrapping your string in {} , specifically when applying it to a component is optional.

Examples

strings.mdx
<Card
    // I can wrap the title with single quotes, 
    // double quotes or backticks.
    title='My title'
    // But because this has an apostrophe, I can't
    // use the single quotes here without escaping it,
    // So I'll use backticks here.
    desc={`This is my description's content.`}
>
...

Experimental String escaping

This will be fully supported in a future update. It may or may not work currently...

If we really wanted to use single quotes inside of another pair of single quotes, or double quotes inside of double quotes, we can do that as:

strings.mdx
<Card 
    // If I really need to include matching quotations within the string itself,
    // I have to lead it with a leading `\` character.
    desc={"This is my \"quotation\" here"}
/>

Booleans

Booleans are just true or false values, indicated by true or false in lowercase. To make things easier, jsx allows a shorthand syntax where when a property is false by default, it can be set true by simply passing the property's name.

This gives a situation where in the following code, shrink and important will both evaluate to true, and some other value, say notImportant will evaluate to false just by omission.

booleans.mdx
<Card 
    shrink={true}
    important
>
...

Numbers

Numbers in javascript are straight-forward, defined exactly as you'd expect. One important property to note however, is that to provide a number as a value to a jsx property, you must wrap the value in curly brackets. This gives something that looks like:

<Grid medium={2} >
...

Note here that 2, and 2.0 are actually not the same thing. Conundrum, like many programming languages, makes a distinction between integers and floats (decimals).

Arrays

Arrays are just lists and are familiar to every programmer, and thankfully, they're incredibly easy to work with in conundrum. Like numbers, the value must be wrapped in a set of {} brackets, but inside of those brackets, the actual Array notation requires another set of square brackets. This ends up looking like the following:

arrays.mdx
// This is an empty array. 
// This pie plot is sad because it has no data, but the syntax is valid.
<PiePlot data={[]} />

To include values within the array, just seperate the normal conundrum syntax (not necessarily jsx syntax, so no extra curly brackets everywhere) of whatever data type you're trying to insert with commas.

arrays.mdx
<MyFakeComponent 
    myArrayOfNumbers={[1, 2, 3, 4, 5]}
    myArrayOfStrings={["One", "two", "three", "four", "five"]}
    myArrayOfObjects={[
        {
            body: "My body",
            value: 2
        },
        {
            body: "My other body",
            value: 3
        }
    ]}
/>

What is much more likely however, is that whatever arrays you do work with inside of Fluster will be generated for you. There is currently a math extension that is in beta that will provide a very numpy like array interface for plotting and mathematical calculations directly within your note.

Objects

'Objects' are at the core of most programming languages, and javascript is no exception. This subject does however start to bridge the gap between what is required to use Fluster and what is the beginning of a software career, but I would encourage more advanced users to learn more here. Objects are defined as a set of key-value pairs, where the value can be almost anything, including another object.

<MyFakeComponent 
    // Notice that there are 2 `{{}}` here.
    // 1 is required for jsx, the other for the actual object.
    // Confusing... I know.
    myObjectProperty={{
        name: "My name",
        value: 2,
        address: {
            street: "1 Main Street",
            city: "North Pole"
        }
    }}
/>
Fluster