How do I type nicely formatted posts into Discourse?

[mark]

Discourse at Mark's Math is built using Discourse, which is widely used open source forum software. Discourse provides two interfaces for text entry - the classic markdown editor and a newer rich editor.

The default editor on Discourse at Mark's Math is the markdown editor, since most university students going into any technical fields should become familiar with markdown at some point. Some folks find that markdown feels too much like code, though, and prefer more direct entry; that's what the rich editor comes in.

I recommend that students start with the markdown editor but you can switch back and forth as you like. In either case, there will be a toolbar at the top of your post that looks like so:

The switch at the left toggles back and forth between markdown and rich . You can read more about each of these in the posts below:

• the markdown editor and
• the rich editor.

[mark]

Using the markdown editor

The default mode of entry for posts in Discourse at Mark's Math is Markdown, which is a useful tool to understand in its own right since it's widely used in

• Website and blogging software, like Squarespace and Wordpress
• Version control systems, like GitHub
• Note taking tools, like Obsidian
• Communication Platforms, like Reddit and Stack Exchange.

Markdown is intended to be a lightweight, easy to read/write syntax to indicate how text should be nicely formatted For example, if I wanted my rendered text to look like this:

Reasons Markdown is awesome

Markdown is really awesome because

• it's easy to read,
• it's easy to write,
• but that's all?
  • Actually, there's a lot more, like the output is awesome!

Reasons markdown is not awesome

• NONE!

I could type:

## Reasons Markdown is awesome
**Markdown** is really awesome because
- it's easy to *read*,
- it's easy to *write*, 
- ~~but that's all?~~
  - Actually, there's a lot more, like the output is **awesome**!
## Reasons markdown is not awesome
- **NONE!**

Note how it's just basic text with a few extra symbols like

• **bold** for bold
• *italic* for italic.
• ~~strike through~~ for strike through

Higher level items include hashtags (like ##) for sections and dashes (like -) for list items. You can take a look at the Markdown cheatsheet already linked for a more complete introduction.

The toolbar

We've already met Discourse's toolbar:

When editing in markdown mode, the toolbar essentially functions as a Markdown assistant. Thus, you can insert the required markdown by pressing

• for bold text
• for italic text.
• for headings
• for hyperlinks
• for block quotes
• for code
• for images
• for bulleted lists
• for numbered lists, and
• for emojis

There are three other buttons on either side of the toolbar:

• that toggles between markdown and rich editors,
• that accesses the AI proofreader, which is particularly convenient for entering math, and
• that provides access to additional options like Math Mode.

These are really not hard to figure out, if you just play around a bit!

Images

The icon in the toolbar is used to include images. When you click on it, you can choose an image from your machine, that image will be uploaded, and the proper Markdown syntax will be inserted into your post.

That's how I inserted the image of the toolbar in the first place!

Dynamic images with Desmos

If you use Desmos, you can create really nice images and make them interactive as well. Here's an example

Note that you can move the h-slider to illustrate one of the fundamental ideas of calculus. The image is a direct embedding of this Desmos graph.

To embed any Desmos graph, simply click the share button in the top right of the Desmos window.

[mark]

Using the rich editor

Discourse’s rich editor is essentially a basic “What you see is what you get” or WYSIWYG editor. From the user’s viewpoint, the immediately obvious difference is that the screen is not split into two parts - a text entry pane and a rendered pane. In their place is a single pane, which is formatted as you type.

The toolbar

We have the same toolbar, though the rich editor is now highlighted in the toggle on the left:

The formatting buttons all mean the same thing, thus

• enters bold text,
• enters italic text,
• enters headings,
• enters hyperlinks,
• enters block quotes,
• enters code,
• enters images,
• enters bulleted lists,
• enters numbered lists, and
• enters emojis.

The special buttons on the right also mean the same thing as with the markdown editor, though, their behavior is slightly different:

• provides access to the proofreader, though, you can’t select text within a math node and
• provides access to additional options and insert math is now essential.

Images

Images, too, work in largely the same way as they do in the markdown editor. One key difference is that iframe embeds from Desmos must be pasted. That’s how I entered this thing:

When I pasted it, though, it looked like so:

Technically, this is an embedded inline node. You’ll see more of this sort of thing, if you enter typeset mathematics in the rich editor!