Are the formatting syntax codes posted on the forum anywhere convenient?
it isn't in the FAQ, and it isn't on a handy help-icon in the post editor. Do you have to go offsite?
Hi @DaveX. I'm not sure I understood correctly what you mean by "formatting syntax codes". Please provide a more detailed description to help me to understand it and make sure I can provide a useful answer to your question.
Although #13 shows the code, if the best way of finding it is to be referred to it, it is poorly documented.
One would be better off with clicking off-site and searching for "discourse formatting" or "markdown formatting" or "BBcode formatting" but none of those quite describes how discourse is implemented here.
Maybe you can do a search for "Arduino forum formatting" and find separate topic posts for separate formatting tags, with varying degrees of quality. Maybe if you know exactly what tag you are looking for, one can find a reply that covers that tag.
Post formatting is poorly documented on the Arduino Forum.
I mean something like:
...but customized for Arduino's implementation.
Something comprehensive enough to be worth having a little '?' icon in the upper right corner of the edit box like this:
Thanks for the clarification.
I agree. I think this should be improved on.
I would not add the information to the introductory forum guide because a new forum user doesn't need to know this information and we need to be very careful to keep that guide as succinct as possible to avoid the "TL;DR LOL" effect. The formatting needs of the new user will be covered by the automatically generated markup provided by the icons on the post composer toolbar.
I would propose the creation of an "Advanced forum usage guide" document to contain markup documentation and other information about using the forum that will be useful to the more advanced users.
Since the users who already had an account before the migration to the Discourse framework in 2021 will not have been through the process, I should mention that, when first entering the site after signing up, new users see a screen overlay that directs them to read a "Greetings" PM from the "@discobot" bot account:
This PM invites them to participate in an interactive tutorial about the basics of using the forum. One of the messages the bot sends during this tutorial includes some instruction in markup as well as a link to a Markdown tutorial:
There is a video at the link above, but if anyone would like to experience the tutorial (the overlay is only shown for new accounts) in person, you can send a private message to @discobot which contains the following text:
@discobot start tutorial
These BBCode examples listed over on Discourse's formatting page don't all work on Arduino's Discourse implementation:
strong
emphasis
underlined
strikethrough
[ul][li]option one[/li][/ul]
[quote="eviltrout"][/quote]
http://bettercallsaul.com
eviltrout@mailinator.com
\nx++\n[spoiler]it's a sled[/spoiler]
[quote="eviltrout, post:1, topic:2"]
...And the listed Markdown-it tests from: and https://markdown-it.github.io/ do not all work here on the Arduino forum:
Advertisement 
- pica - high quality and fast image
resize in browser. - babelfish - developer friendly
i18n with plurals support and easy syntax.
You will like those projects!
h1 Heading 
h2 Heading
h3 Heading
h4 Heading
h5 Heading
h6 Heading
Horizontal Rules
Typographic replacements
Enable typographer option to see result.
(c) (C) (r) (R) (tm) (TM) (p) (P) +-
test.. test... test..... test?..... test!....
!!!!!! ???? ,, -- ---
"Smartypants, double quotes" and 'single quotes'
Emphasis
This is bold text
This is bold text
This is italic text
This is italic text
Strikethrough
Blockquotes
Blockquotes can also be nested...
...by using additional greater-than signs right next to each other...
...or with spaces between arrows.
Lists
Unordered
- Create a list by starting a line with
+,-, or* - Sub-lists are made by indenting 2 spaces:
- Marker character change forces new list start:
- Ac tristique libero volutpat at
- Facilisis in pretium nisl aliquet
- Nulla volutpat aliquam velit
- Marker character change forces new list start:
- Very easy!
Ordered
-
Lorem ipsum dolor sit amet
-
Consectetur adipiscing elit
-
Integer molestie lorem at massa
-
You can use sequential numbers...
-
...or keep all the numbers as
1.
Start numbering with offset:
- foo
- bar
Code
Inline code
Indented code
// Some comments
line 1 of code
line 2 of code
line 3 of code
Block code "fences"
Sample text here...
Syntax highlighting
var foo = function (bar) {
return bar++;
};
console.log(foo(5));
Tables
| Option | Description |
|---|---|
| data | path to data files to supply the data that will be passed into templates. |
| engine | engine to be used for processing templates. Handlebars is the default. |
| ext | extension to be used for dest files. |
Right aligned columns
| Option | Description |
|---|---|
| data | path to data files to supply the data that will be passed into templates. |
| engine | engine to be used for processing templates. Handlebars is the default. |
| ext | extension to be used for dest files. |
Links
Autoconverted link GitHub - nodeca/pica: Resize image in browser with high quality and high speed (enable linkify to see)
Images
Like links, Images also have a footnote style syntax
With a reference later in the document defining the URL location:
Plugins
The killer feature of markdown-it is very effective support of
syntax plugins.
Emojies
Classic markup:
:crush:
:tear:
Shortcuts (emoticons):
see how to change output with twemoji.
Subscript / Superscript
- 19^th^
- H~2~O
<ins>
++Inserted text++
<mark>
==Marked text==
Footnotes
Footnote 1 link[^first].
Footnote 2 link[^second].
Inline footnote^[Text of inline footnote] definition.
Duplicated footnote reference[^second].
[^first]: Footnote can have markup
and multiple paragraphs.
[^second]: Footnote text.
Definition lists
Term 1
: Definition 1
with lazy continuation.
Term 2 with inline markup
: Definition 2
{ some code, part of Definition 2 }
Third paragraph of definition 2.
Compact style:
Term 1
~ Definition 1
Term 2
~ Definition 2a
~ Definition 2b
Abbreviations
This is HTML abbreviation example.
It converts "HTML", but keep intact partial entries like "xxxHTMLyyy" and so on.
*[HTML]: Hyper Text Markup Language
Custom containers
::: warning
here be dragons
:::
Cheat Sheet
There is a "cheat sheet" online for this. Maybe it will help you. But you're right - we would need a guide (I say) for formatting. I would find that useful as well. But I also believe that HTML formatting works too! (Or Text with color: [color=red]Problems[/color])
Problems
But that creating task lists do not work here, for example. Have you noticed this before?
A heading is actually also made with markdowns with # but here with:
Download
1 Like
I don't know that it needs to be "advanced" rather than complete. Maybe "Forum syntax" is descriptive enough. It is a level of complexity to partition the documentation between "beginners" and "advanced users", and I let stuff flow out of my brain fast enough that I'm no longer advanced if I don't use it every day. I'd say there's no need to complicate the intro documentation with all this, but the UI for forum edit box should have a link to complete documentation--accurate syntax should be only one click away. I think a '?' link in the upper corner of the edit box be more useful than the emoji popup and would be natural, obvious tool.
Good, readily accessible documentation is how you convert beginners into advanced users.
Even though the information might be documented deep in some tutorial somewhere, pointing users to a multiple-click/page diversion to figure out how to strikethtough text or writesubscripts is bad help to give, and infuriating/alienating bad help to receive.
1 Like
We don't need a GUIDE !
What we do need is what we had in SMF.
AFAIK it is also available for discourse ?
This is another topic on something that was discussed to death.
Instead we were essentially told to use markup instead and that was essentially one person.
Will say this again.
Noobs and many non noobs should not be FORCED to learn markup / markdown.
They should not be asked to wander the internet looking for how to markup / markdown.
The forum should provide the tools they need in an EASY TO USE format.
Want to colour a word red then just select it and the colour from a drop down pallete.
Want to raise the text size the select it from a short drop down.
1 Like
It is no good suggesting changes to the forum unless they exists as options or an addon that can be turned on
Also, do not assume that when others use the forum it looks the same as when you use it as it depends on a number of factors. For instance, here is my current message edit window
Where would your suggested '?' link appear ?
It is not the only one available either.
@dax1 could we have your input or somebody else knowledgeable in this area ?
On that snapshot, I'd suggest on line 2 next to the gear icon.
I don't know what's possible within the constraints of the software, but I would think if it is possible to add a red highlighting tool, a link to a syntax page would be possible.
Oh, I just tried clicking on the other icons an noticed the [details="name"][/details] tag on the gear icon. If a help or syntax link isn't possible in the icons, maybe it could fit in the gear icon menu.
Spoiler
A good UI has help accessible at the point of use.
1 Like
Or 5 browser tabs of markdown / up / sideways help pages open with different results and outcomes for the same effect !
I am still looking for something that can render this:
$$
\sum_{k=0}^{\infty} \frac{(-1)^{k}}{(2k+1)^3}=\frac{\pi^3}{32}.
$$
MathJax?
That is what I proposed too,
But apparently there is not enough demand for it:
Maybe mentioning it once in a while will get other people enthusiastic about the idea.
1 Like
Asking for a full or better toolbar became a "bang your head on a wall" exercise.
GLADOS says we need to learn markup/down.
And there is your brick wall.
IIRC there are still posts lingering in the depths about this very topic.
You will find my support for a better toolbar, and a solid brick wall against such things in those posts !
It is not so much "lack of support" but a lack in other areas that should I mention may get me another spanking LOL.
Spoiler text can be hidden in 'details' markup:
[details="Summary text"] This text will be hidden [/details]
This topic was automatically closed 180 days after the last reply. New replies are no longer allowed.