Arbital Markdown

https://arbital.com/p/arbital_markdown

by Alexei Andreev Apr 2 2015 updated Sep 15 2016

All about Arbital's extended Markdown syntax.


[summary: Arbital uses Markdown with many custom extensions to help you create awesome explanations. Become a pro editor by learning how to create todos, greenlinks, page summaries, [arbital_note notes], hidden text, and insert LaTeX!]

The Arbital editor uses Markdown syntax for editing the pages. If you've used Reddit or any of the StackOverflow, it's the same syntax. Here is a helpful intro to Markdown syntax.

[toc:]

Arbital Markdown syntax

Arbital adds a few extra features to Markdown syntax.

Table of contents

[toc:] creates a table of contents, like the one above.

Greenlinks

[todo: Add note about the Intrasite Link button on the toolbar.]

You can quickly link to a page by using [id] or, even better, [alias] syntax. For example:
<a href="arbital_markdown.html">Arbital Markdown</a> => Arbital Markdown
[Arbital\_markdown] => Arbital Markdown

%%hidden(Advanced): If you want the inserted title to be lower-cased, add a dash:
<a href="value_alignment_problem.html">Value alignment problem</a> => Value alignment problem
<a href="value_alignment_problem.html">Value alignment problem</a> => Value alignment problem

If you want to specify what text shows up as the link, use [alias text]. For example:
<a href="arbital_markdown.html">Custom link</a> => Custom link

If you link to a page that doesn't exist, the link will show up red:
[definitely\_doesnt\_exist Doesn't exist] => [definitely_doesnt_exist Doesn't exist]

If you want to just create a red link with some text:
[ create a page for this concept later] => [ create a page for this concept later]

If you want to mention someone use [@userId] or [@userAlias]:
<a href="AlexeiAndreev.html">Alexei Andreev</a> => Alexei Andreev
<a href="AlexeiAndreev.html">Alexei Andreev</a> => Alexei Andreev
NOTE: the user will get an update if the mention is in a comment. %%

Summaries

You can set the page's summary, which shows up in greenlink popovers and other places. For example:
[summary: Summary of the page goes here. *Markdown* is okay!]
Or to set a specific summary:
[summary(Technical): Very technical summary. *Markdown* is okay!]
Make sure that the entire summary block is in a paragraph of its own.

Hidden text

You can create hidden text:

%%hidden(Button text):
Hidden text goes here.
%%

%%hidden(Button text): Surprise! %%

You can use this for hiding problem answers and asking the user to solve the problem themselves before clicking the button to see the correct answer. Button text is required.

[arbital_note Notes]

You can create notes, which are snippets of text hidden behind a question mark. You can put footnotes or other text that might be interesting to some users, but not to everyone. For example:
%note:Fun note text!% will show up as: %note:Fun note text!%

%%%comment:
[1]: this is not something we want to advertise at this time.  
You can embed [3r votes] from other pages. For example:  
`[vote: 3r]` creates this voting bar:  
[vote: 3r]
%%%

Todos, [arbital_inline_comments comments], and [arbital_fixme fixmes]

You can leave todo markers for yourself or other authors. For example:
[todo: finish this section] [todo: finish this section]
%%todo: You can put any funky *markdown* syntax here including `[Arbital\_greenlink links]`. %%
This will only appear in the top quality bar when expanded, not the page text. Red links and "todo" markers count towards the todo score, which you will see next to the pages on the Explore and your Profile pages. %%todo: You can put any funky markdown syntax here including links. %%

Similarly, you can leave comments or fixmes for other authors, but without increasing the todo count. For example:
[comment: there has got to be a better metaphor for this] [fixme: this needs to be fixed, but I've got it] [comment: there has got to be a better metaphor for this] [fixme: this needs to be fixed, but I've got it] <pre>%%comment: You can put any funky *markdown* syntax here. You can vary the number of %s to envelop other similar blocks. %%</pre>
Again, this doesn't show up for the reader in any way.

%%comment:
You can put any funky *markdown* syntax here. You can vary the number of %s to envelop other similar blocks.
%%

[todo: questions and path generation]

[todo: conditional text]

LaTeX

If you're new to LaTeX you may want to read the Wikibooks guide

You can use \$ to create inline mathematical expressions, e.g. $~$ax^2 + bx + c \= 0$~$ will be displayed as: $~$ax^2 + bx + c = 0$~$
And \$\$ to create centered math expressions, e.g. $$~$\\lim\_{N \\to \\infty} \\sum\_{k\=1}^N f(t\_k) \\Delta t$~$$ will be displayed as: $$~$\lim_{N \to \infty} \sum_{k=1}^N f(t_k) \Delta t$~$$

The editor can get a little slow if you are editing very LaTeX-heavy pages. If this is an issue for you, let us know, and in the meantime you can disable MathJax on the settings page.


Comments

Alexei Andreev

Andrew Critch, these are all the Arbital-specific markdown addons we have.

Maelle Andre

Is "coment" (below) a typo?

"[comment: there has got to be a better metaphor for this] %%coment: this supports line breaks, but needs to be its own paragraph. You can vary the number of |s to envelop other similar blocks. "

Alexei Andreev

Fixed, thanks!

Nate Soares

You can leave "todo" markers for yourself or other authors\. For example: \[todo: finish this section\] %%todo: This supports line breaks, but needs to be its own paragraph %% This will not show up on the page in any way\. Red links and "todo" markers count towards the todo score, which you will see next to the pages on the Explore and your Profile pages\.

What's with the %% marks? Can all [square bracket thingies] be turned into percent-demarcated blocks? How do the percent-demarcated blocks work?

Alexei Andreev

It's a totally made up, arbitrary syntax that makes no sense and NEEDS TO GO.

Nate Soares

I mean, I wasn't going to say it myself, but that was my general impression :-p

(I'm also dubious on the single square bracket, though it seems to be working fine at the moment.)

Regex Rationalist

"$~$ax2+bx+c=0$~$ will be displayed as: $~$ax2+bx+c=0$~$"

Displays instead of

"S ax^2 + bx + c = 0 S will be displayed as: $~$ax2+bx+c=0$~$"

(Where S = dollar sign, putting commenting syntax ironically duplicates the error.)

The same problem applies to the centered version.

Now, for some reason the editor displays it just fine, but the actual page does not. (At least on my screen.) The same thing occurs with the previewing of comments versus actually publishing the comments.

"Smart links You can quickly link to a page by using '[id]' or, even better, '[alias]' syntax. For example:

<a href="arbital_markdown.html">Arbital Markdown</a> => Arbital Markdown
<a href="arbital_markdown.html">Arbital Markdown</a> => Arbital Markdown"

Is 3w both the alias and the id?

Alexei Andreev

Thanks for bringing this up. The \$ issue is relatively new, since we've been changing the editor a lot recently. The <a href="arbital_markdown.html">Arbital Markdown</a> issue is old, and I've never got around to it.

But both are fixed now! :)

Eric Leese

There appears to be an inconsistency in the rendering of this page and its rendering in the preview pane when editing this page. The LaTeX extension behaves differently, so on this page we see only the rendered expressions twice, when what we are meant to see is the markdown and then the rendered version of the equation. But if you go to edit page, in the preview pane it is correct. Is there a way to file a bug?

Alexei Andreev

Thanks for bringing this up. I fixed the core part of the issue: you can now use backticks to escape LaTeX rendering. However, if you use bold, the behavior is still inconsistent between the editor and live view. We'll fix that in due time.

Usually commenting on the page is fine for reporting issues, but there is also a "Leave feedback about Arbital" button under the quick menu in the bottom right corner.

Tsvi BT

Is there a way to link to a section within a page? (E.g. for tables of contents.)

Eric Bruylant

There is now! This page even has a TOC.

Chris Holden

Does arbital markdown use any of the markdown table formats? Can latex be included within? Is there a way to insert an html table into a page or parse other html?

Alexei Andreev

Good question. We don't have table or HTML support right now, but I"ll bump up the priority on that.
We do support LaTeX. I think it's not rendering correctly on Primer on Infinite Series because of <td> and other such tags.

Malcolm Ocean

Tiny but important remark:

It seems weird to me that the links in the TOC are blue, since blue normally means external link whereas green means internal link. But maybe there should be a link color that's further towards green on the blue-green spectrum of links, for links that are on the page itself? At any rate, making the TOC links greyish or greenish by default seems like a good plan.

Alex Peterson

Can we add support for colors? I would find it very helpful to be able to color code words that relate to each other, in the way that redpenblackpen and 3blue1brown do.