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.
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
Below is the output of
Docs?
| 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.
| 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
, ... |
Styled text follows the same rules as markdown, with
The optional id allows me to reference it by number: 1
The language is optional, but a complete list of supported languages can be found [here]()
My python codeblock:
v = np.linspace(0, spc.c, 1000)
The last block inside of the brackets optionally specifies the language.
List items start with a
-
or a number, and can optionally contain a checkbox.
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.
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..
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?
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:
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.
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.
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.
<
and a capital letter.
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 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
/>
.
This
Card
component accepts
children
, so we use the
>
closing bracket on the opening tag.
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:
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.
'
, double
"
, or a backtick "`" (top left of the keyboard.).
{}
, specifically when applying it to a component is optional.
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:
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.
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:
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 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:
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.
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' 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.