97 votes

Tildes and comment formatting, markdown: a quick and dirty guide

Posted by AugustusFerdinand (edited )
Tags: guides, formatting, markdown

At the suggestion of a certain heathen who shall remain unnamed. I'm tossing up a quick and dirty comment (and post text) formatting guide. There is a formatting guide in the docs/wiki with a link just above the comment box, but it can be a bit much to digest.

*italics*
**bold**
~~strikethrough~~
[Text goes here](URL goes here)
<small>small text</small> 
<sub>subscript</sub>
<sup>superscript</sup>
# headline
`code which removes the formatting and makes it look like this block`
* bulleted
* lists
1. and
1. numbered
1. lists

Spoilers is a bit more complicated, the <details> start and end </details> is required, but the <summary> start and end </summary> is not unless you want text in the summary or you want the summary to be blank.

<details>
<summary>Summary text!</summary>

Body text inside spoiler!
</details>
For example if you leave out the summary code then the box just says "Details" like this.
Or you can have a summary...

...like this.

Or by leaving the text between the summary code blank you can have the box be empty but still have spoiler text within

You can use formatting like bold, italics, or even...
...spoilers within spoilers! ...but you have to leave an extra line above this or it *won't work* and your formatting will be revealed to **all!**

Three underscores (or dashes, but dashes require an extra line) in a row on their own line creates a blank line to divide a topic...
---

You also have a sub-headline text option by putting a single dash under text...
-
...or headline text by putting an equal sign under text.
=

If you like userscripts (who doesn't?) you can install extensions like ViolentMonkey that allow you to install little bits of code like the Tildes Formatting Toolbar that can change/improve the sites you use and make formatting here a breeze.

Do use the formatting responsibly, but here are examples for bold, italics, strikethrough, links, small text, subscript, superscript,

headline text,

sub-headline text,

code,

  • bulleted
  • lists,
  1. and
  2. numbered
  3. lists

Most formatting can be combined as well such as superscripts, lines, and small text to make...

...sentences with a...1

1...footnote

21 comments

  1. [2]
    riz
    (edited )
    Link
    A quick one on tables too. To have a table, just draw (I mean, type) something out that looks like a table but use the pipe character (|) to denote the start and end of a column. | Tables | Are |...
    • Exemplary

    A quick one on tables too.

    To have a table, just draw (I mean, type) something out that looks like a table but use the pipe character (|) to denote the start and end of a column.

    | Tables | Are | Simple |
|--------|-----|--------|
| Some | data | here |
| More | data | for example |
| Some | *light* | **markdown** too |

    The first line will render as a heading row in your table (as it should). The second line, which is also mandatory but easily missed, defines how the data in each of the columns should be aligned, but we discuss more on alignments in the next example. You can use additional spaces before and after the cell data to make the pipe characters look aligned, but it's not important at all. So, this is the table the above markdown yields:

    Tables Are Simple
    Some data here
    More data for example
    Some light markdown too

    Now for the example with alignments specified on the columns. Note, the colon (:) characters that are now there in the second line:

    | Tables           |     Can be    | Optionally Aligned |
|------------------|:-------------:|-------------------:|
| First column is  |  left-aligned |              $1600 |
| Second column is |    centered   |                $12 |
| Third column is  | right-aligned |                 $1 |

    If a colon is present on both ends of the dashes (-), as is on the second column, then all the values in the column will be center aligned. If the colons are present only on the right, or left side of the dashes, then they will be aligned respectively. Note that left alignment is the default so no need to mention colons in that case. This gives us the table:

    Tables Can be Optionally Aligned
    First column is left-aligned $1600
    Second column is centered $12
    Third column is right-aligned $1

    As an aid, I often use this online table generator: https://www.tablesgenerator.com/markdown_tables when I want my raw markdown tables to also look aligned, or when I'm not sure where I might have done something wrong.

    The Tildes doc on text formatting does cover most of what is said here but I felt like we could be slightly more wordy here. Tildes doc: https://docs.tildes.net/instructions/text-formatting#tables

    A slight word about the syntax discussed... It's not necessary that this exact syntax, or even tables at all will work in other platforms that also support Markdown . The original Markdown spec is very ambiguous about what it supports (and even how it supports) but it clearly does not support tables. The CommonMark spec (which Tildes uses) gets rid of Markdown's ambiguity and makes the original Markdown spec more standard, but it doesn't support tables as well. Tildes makes tables supported by using at least one CommonMark extension. With that said, this syntax is the most popular one as is used by GitHub, GitLab, Reddit, etc. It's safe to assume that wherever Markdown tables are supported, this syntax should work.

    11 votes
    1. riz
      Link Parent
      With the tables in markdown mentioned, I often also prefer the html way. Like OP has mentioned in case of <details>, tables in html have to start with <table> and end with </table>. Each row...

      With the tables in markdown mentioned, I often also prefer the html way. Like OP has mentioned in case of <details>, tables in html have to start with <table> and end with </table>. Each row starts with a <tr> (and optionally end with a </tr>). Each table cell starts with a <td>, and optionally end with a </td>. So here is an example of a simple table in html:

      <table>
<tr>
<th>Heading Col 1
<th>Heading Col 2
<th>Heading Col 3

<tr>
<td>First item, Col 1
<td>First item, Col 2
<td>First item, Col 3

<tr>
<td>Second item, Col 1
<td>Second item, Col 2
<td>Second item, Col 3

<tr>
<td>Third item, Attr 1
<td>Third item, ...
<td>Third item, ...
</table>

      This is how the table looks rendered:

      Heading Col 1 Heading Col 2 Heading Col 3
      First item, Col 1 First item, Col 2 First item, Col 3
      Second item, Col 1 Second item, Col 2 Second item, Col 3
      Third item, Attr 1 Third item, ... Third item, ...

      To me, this style of table looks readable enough in raw text and since each cell data is in its own line, I have the flexibility to:

      • Break down long text in any cell into multiple lines
      • Not worry about how the table looks un-aligned in raw text, since, nothing to align
      • Easily add other html tags if needed, like adding a <caption> tag

      A little disclaimer: I understand that regular users of html (myself included) might scoff at the idea of not closing the seemingly "dangling" tags that were left opened, but I find it passable in this case, since we're all just users here, writing something in a text field; and not in the source code of an html file. Apart from that, the w3c spec also allows to leave <tr> tags opened if followed by another <tr> tag: https://www.w3.org/html/wg/spec/syntax.html#optional-tags

      8 votes
  2. onceuponaban
    Link
    Of note is that the formatting toolbar is also a feature found in the Tildes ReExtended browser extension.

    Of note is that the formatting toolbar is also a feature found in the Tildes ReExtended browser extension.

    15 votes
  3. AgnesNutter
    Link
    This heathen thanks you :)

    This heathen thanks you :)

    8 votes
  4. [7]
    updawg
    Link
    Oh, hell yeah That is super annoying to type, though, especially on a phone.

    Oh, hell yeah

    That is super annoying to type, though, especially on a phone.

    4 votes
    1. [6]
      dysthymia
      Link Parent
      Adding a keyboard shortcut on your phone for some of the more annoying things may be something that you find very useful. Especially if you know you'll use some of these a lot.

      Adding a keyboard shortcut on your phone for some of the more annoying things may be something that you find very useful. Especially if you know you'll use some of these a lot.

      1 vote
      1. [5]
        riz
        Link Parent
        I suggest Unexpected Keyboard for this. It's like the full keyboard but with excellent UX for mobile. It can even <Ctrl+v> to paste, <Ctrl+Backspace> to delete a word, and all that. Typing this...

        I suggest Unexpected Keyboard for this. It's like the full keyboard but with excellent UX for mobile.

        It can even <Ctrl+v> to paste, <Ctrl+Backspace> to delete a word, and all that.

        Typing this comment using it too!

        5 votes
        1. [3]
          updawg
          Link Parent
          Good idea but with just Gboard (and pretty much all standard keyboards) you can just put things into your custom dictionary ¯\_(ツ)_/¯ (that's "zqshrug" for me).

          Good idea but with just Gboard (and pretty much all standard keyboards) you can just put things into your custom dictionary ¯\_(ツ)_/¯ (that's "zqshrug" for me).

          2 votes
          1. [2]
            riz
            Link Parent
            That looks very cool. Gotta try it for my self. But how do you manage the symbols with that approach? Like: _, [, |? I guess you could setup something like typing zqlink to give you []() and then...

            That looks very cool. Gotta try it for my self.
            But how do you manage the symbols with that approach? Like: _, [, |?

            I guess you could setup something like typing zqlink to give you []() and then move the cursor between the braces.

            1 vote
            1. updawg
              Link Parent
              Yes, perhaps I would do zqsmall for and qzsmall for . But the individual symbols aren't an issue. The problem is pressing ?123--=\<--<--s--m--a--l--l--?123--=\<-->, then type what I want to be...

              Yes, perhaps I would do zqsmall for and qzsmall for . But the individual symbols aren't an issue. The problem is pressing ?123--=\<--<--s--m--a--l--l--?123--=\<-->, then type what I want to be small, then ?123--=\<--<--?123--s--m--a--l--l--?123--=\<-->.

        2. dysthymia
          Link Parent
          I have to say, I've essentially been using this keyboard since approximately when you suggested it, and it's been wonderful

          I have to say, I've essentially been using this keyboard since approximately when you suggested it, and it's been wonderful

  5. chromebby
    Link
    Yay, thanks! This is my first bookmark and will come handy.

    Yay, thanks! This is my first bookmark and will come handy.

    2 votes
  6. [4]
    horseplay
    (edited )
    Link
    I'm hung up on the links instructions, because whenever I've tried, it's not working. I used brackets for the text, and parenthesis for the link, for example, brackets but it shows up in the...

    I'm hung up on the links instructions, because whenever I've tried, it's not working. I used brackets for the text, and parenthesis for the link, for example, brackets but it shows up in the comment without the link inserted, and instead it still shows what I literally type. And upon previewing this comment, it still did not due what the formatting help says it will do.

    I'd love anyone to instruct me about whatever error(s) I'm making.

    edit: I took the space between the two components out, as suggested by the reply beneath (Thank you!), and it made the link correct. So the format needs to be [text]no space(link) but in every instruction I'm reading it appears to me like [text]space(link), even on the instructions in this post.

    2 votes
    1. [2]
      mycketforvirrad
      Link Parent
      There isn't a space between the two components.

      There isn't a space between the two components.

      4 votes
      1. horseplay
        Link Parent
        Are you saying there should or should not be a space between them? *edit: Never mind. There should not.

        Are you saying there should or should not be a space between them? *edit: Never mind. There should not.

        3 votes
    2. AugustusFerdinand
      Link Parent

      It looks like a space because of the code markdown makes ]( look like there's a space between them despite that not being the case.

      3 votes
  7. Corsy
    Link
    Solid, thank you

    Solid, thank you

    1 vote
  8. [3]
    g33kphr33k
    Link
    Please add a formatting bar to the comment box that can be enabled or disabled. Mobile typing is a killer for formatting if you don't know markdown off the top of your head. It on needs the basics...

    Please add a formatting bar to the comment box that can be enabled or disabled. Mobile typing is a killer for formatting if you don't know markdown off the top of your head. It on needs the basics like italics, bold, strike through. The usual typing aids.

    1 vote
    1. Algernon_Asimov
      Link Parent
      The OP can't do what you're asking. They're just describing the existing markdown features. They don't run Tildes. They don't write code for Tildes (as far as I know). They're just listing the...

      The OP can't do what you're asking. They're just describing the existing markdown features. They don't run Tildes. They don't write code for Tildes (as far as I know). They're just listing the available formatting features in one easy-to-read guide.

      This formatting bar you've requested is already included in the ever-growing list of features to be added to Tildes in the future. We'll get it... one day!

      In the meantime, one helpful Tilder has created a browser extension which includes a toolbar showing the various formatting options, which will do exactly what you're asking for here.

      And, as a final suggestion... if you want to request a product feature, I highly recommend that you post a new topic in ~tildes for more visibility, rather than burying it as a comment on someone else's topic.

      9 votes
    2. riz
      Link Parent
      I think you can use a browser extension that enhances the current UI/UX of Tildes, much like what RES was for Reddit. Tildes ReExtended should have what you want:...

      I think you can use a browser extension that enhances the current UI/UX of Tildes, much like what RES was for Reddit. Tildes ReExtended should have what you want: https://tildes.net/~tildes/17kq/tildes_reextended_has_been_updated_and_is_also_back_on_the_chrome_web_store_again

      And for iOS, an app is in the works. Surfboard: https://tildes.net/~tildes/17kq/tildes_reextended_has_been_updated_and_is_also_back_on_the_chrome_web_store_again

      Android users... Might feel left out but not necessarily so. Because...

      For the basics like you have mentioned, I think Markdown's syntax is intuitive enough that bolds, italics, strikethroughs don't very strongly suggest an upgrade to the simple Text Field.

      • Surround with one * to add first level of emphasis: italics
      • Surround with two * for added emphasis, i.e. bold
      • Surround with three * for even more... Italic and bold
      • Strikethrough is just two tildes (~): ~~Cut me~~: Cut me.

      Lists, and smalls are simple enough too.

      But I do admit, the UX could improve, if for example I could highlight the parts of text I want make bold, and just press a button to do so. Right now, I can, select what I want to bold, choose Cut from context menu, add the *s, go between the *s and paste.

      On the other hand, If I do put down my preference, it's on the simple text field.

      2 votes