Formatting tips specific to the Opus forum

The Directory Opus forum runs on an open source package called Discourse. Below are some tips for using the Discourse forum software, specific to things we often need to do when talking about Directory Opus.

See Also: Discourse New User Tips and Tricks for the basics of how Discourse works, not specific to the Opus forum.

Including images in your posts

  • Including images in your post is easy. If you know how to take a screenshot and paste it into a Word document, you already know how to do it.

  • You can paste images from the clipboard when editing a message just like you can paste text in.

  • You can also drag and drop image files into the message editor.

  • When you add an image file, the message preview you see to the right of the editor lets you resize the image easily by hovering the mouse over it. Links will appear below the preview image that let you resize it to certain fixed percentages of the original size.

Paths and \backslashes

  • Normal paths with no double-backslashes work fine as-is.

    e.g. C:\Program Files can be typed as-is.

  • However, UNC paths cause problems. This is because a double-backslash gets converted into a single backslash.

    If you type \\server\share you'll only see \server\share

    You need to type \\\\server\share to get \\server\share

    Alternatively, you can use an inline code block using ` ... ` backticks.

    For example, `\\server\share` will turn into \\server\share

    Incidentally, to type an actual backtick, you escape it with a backslash: \` turns into `

  • Paths with * wildcards and certain other symbols will cause problems. Use a double-slash to avoid them.

    For example, C:\* will turn into C:*

    You need to type C:\\* to get C:\*

  • If in doubt, it never hurts to use two backslashes instead of one, unless you're in a code block.

< Angle-brackets >

  • Most uses of < and > in sentences do not require anything special.

  • One exception is when something looks like an HTML tag.

    For example, <this> or <this/> or </this> will all vanish completely if typed as-is.

    You can work around this using HTML entities:

    &lt; turns into <
    &gt; turns into >
    &lt;this&gt; turns into <this>

  • You can also use inline code blocks, as we saw with the paths above.

    For example, `<this>` will turn into <this>

@ Ats

  • @ symbols are used a lot in Opus commands to add modifiers to the commands.

  • @ symbols are also the way Discourse lets you direct part of a message to another user, so they are notified about your post. For example, typing @⁠Leo will turn into @Leo and notify me about your post.

  • If you type a modifier like @keydown that (probably!) isn't a username, you don't need to do anything special. But if you want to type @⁠Leo or similar without it turning into a username and notification then there are a couple of methods:

    @&#x2060;Leo will turn into @⁠Leo

    • The &#x2060; part inserts a special zero-width character between the @ and the name.

    `@Leo` will turn into @Leo

  • Note that the nicer HTML entity &commat; works in the post preview but will not work in the actual post after you submit it!

* Asterisks *

  • Many asterisks will be fine as-is, but if they are around a word then they'll be interpreted as formating.

    *word* turns into italics word

    **word** turns into bold word

    ***word*** turns into bold italics word

  • If you want a literal * asterisk in those situations, you can use \* to escape it:

    \*word\* turns into *word*

  • Since \* turns into a single * you have to be careful with wildcards like C:\*. As already mentioned in the section on paths and backslashes, above, you'd need to type something like C:\\* (or C:\\\* if you want to be extra safe/explicit, but it's not necessary).

  • You can also use &ast; to get a literal * character.

  • And you can use inline code blocks. `*word*` turns into *word*

Commands:

  • Commands can normally be typed as-is, but it's nice to highlight them so it's clear where the commands and words talking about them are separated.

  • Use ` ... ` backticks if you want to highlight a command mid-sentence.

    For example, `Go PATH=/desktop` will turn into Go PATH=/desktop in the middle of a sentence.

  • For multiple lines, you can use [code] ... [/code] for code blocks:

    [code]
    @keydown:none
    Copy
    @keydown:shift
    Copy AS
    [/code]

    will turn into:

      @keydown:none
      Copy
      @keydown:shift
      Copy AS
  • Alternatively, use three backticks either side like ``` ... ``` for code fences:

    ```
    @keydown:none
    Copy
    @keydown:shift
    Copy AS
    ```
    will turn into:

    @keydown:none
    Copy
    @keydown:shift
    Copy AS
    
  • For pre-formatted text that isn't on a highlighted background, you can also use <pre>...</pre> tags:

    <pre>
    @keydown:none
    Copy
    @keydown:shift
    Copy AS
    </pre>

    will turn into:

@keydown:none
Copy
@keydown:shift
Copy AS
  • Be careful with all of the code block and pre-formatted text options, as they tend to eat anything placed on a line directly after them. You need a blank line before you have anything else.

    That can make them hard to use within lists. Speaking of lists...

Lists

  • Using code blocks in bullet-point and numbered lists can get complicated, but as general rules:
    • Within list items, you need to avoid empty lines in your markup.

      Use <br> to insert an empty line without breaking the list item if you want to space things out or have multiple paragraphs.

    • It's easier to simply not use code blocks inside of lists, but if you really want to (as I did myself in this post!), you normally need to indent the whole block, including the tags or fence around it, to the same level as the list item you are in.

    • Multiple levels of indentation is also how you do nested lists.

      • Like.
        • This
          • If it doesn't work, add a few more spaces and it probably will. :slight_smile:
    • But after messing around with lists, make sure the rest of your post still looks right, as if the forum gets confused it can cause really strange results, and lists are particularly fragile.

Script Code

  • We've configured the forum to show VBScript and JScript code in different colors, to help you tell them apart. This is in addition to the automatic syntax highlighting which Discourse supports.

  • If you put VBScript or JScript code into blocks, the forum will do a pretty good job of guessing which language you have used and automatically highlighting things.

  • That said, you can override this for better results, or in situations where you don't want it.

JScript (Javascript):


[code]
function moo() {
   // Implicit [ code ]
   var x;
   return x + 1;
}
[/code]

will turn into:

function moo() {
   // Implicit [ code ]
   var x;
   return x + 1;
}

Similarly,

```
function moo() {
   // Implicit ```
   var x;
   return x + 1;
}
```

will turn into:

function moo() {
   // Implicit ```
   var x;
   return x + 1;
}

The forum automatically detects that the code is JScript but is conservative about how it formats things. (At least at the time of writing.)

You can get slightly nicer formatting if you explicitly request javascript.

You must specify javascript as the language and not jscript. While jscript is more technically correct for Opus scripts, the forum doesn't know what it is, and jscript is part of the javascript family.

The language name is case-sensitive. "Javascript" and "JavaScript" will not work, only "javascript" in all lowercase.

```javascript
function moo() {
   // Explicit ```javascript
   var x;
   return x + 1;
}
```

will turn into:

function moo() {
   // Explicit ```javascript
   var x;
   return x + 1;
}

Note how the function name is in red and bold in the last example, while it was not in the others. (Edit: That distinction is no longer the case. It seems the forum software's auto-detection improved over the years.)

The other advantage of being explicit is it means you aren't relying on the forum's ability to guess the language, which will probably go wrong sometimes.


Finally, you can explicitly tell the forum that something is not to be highlighted as script code, by specifying plain like this:

```plain
function moo() {
   // Explicit ```plain
   var x;
   return x + 1;
}
```

will turn into:

function moo() {
   // Explicit ```plain
   var x;
   return x + 1;
}

This is case-sensitive. "Plain" or "PLAIN" will not work; only "plain" in lowercase.


VBScript:

[code]
option explicit
function moo
  ' Implicit // [ code ]
  dim x
  moo = x + 1
end function
[/code]

will turn into:

option explicit
function moo
  ' Implicit // [ code ]
  dim x
  moo = x + 1
end function

```
option explicit
function moo
  ' Implicit ```
  dim x
  moo = x + 1
end function
```

will turn into:

option explicit
function moo
  ' Implicit ```
  dim x
  moo = x + 1
end function

Explicitly specifying the language as vbscript avoids the forum having to guess which language is being used.

This is case-sensitive. "VBScript" and similar will not work, only "vbscript" in all lowercase.

```vbscript
option explicit
function moo
  ' Explicit ```vbscript
  dim x
  moo = x + 1
end function
```

will turn into:

option explicit
function moo
  ' Explicit ```vbscript
  dim x
  moo = x + 1
end function

As we saw above, you can explicitly tell the forum not to highlight something as VBScript by specifying plain as the language.

This is case sensitive. "Plain" and "PLAIN" will not work; only "plain" in lowercase.

```plain
option explicit
function moo
  ' Explicit ```plain
  dim x
  moo = x + 1
end function
```

will turn into:

option explicit
function moo
  ' Explicit ```plain
  dim x
  moo = x + 1
end function

Hiding things in collapsible sections

Sometimes it's useful to include a lot of detail, like a long script or log file, but you don't want it to take up a lot of space.

You could add the extra information to the post as an attachment, e.g. in a .text file or zip file.

But using "details" boxes is another option.

If you type this:

[details=My Heading Line]
Lots and lots of details
That you cannot see unless you expand this section.
Peekaboo!
[/details]

It will turn into this:

My Heading Line

Lots and lots of details
That you cannot see unless you expand this section.
Peekaboo!

(Try clicking on the line above to expand it.)

Sometimes the preview lies :slight_smile:

Always check your post after submitting.

When doing complicated things, you may find the end result is not the same as what the preview was showing as you typed your post!

Discourse is evolving

Discourse, the forum software we are using, is quite new and still evolving. Sometimes when we update to a newer version, some of the rules and tricks above change.

If you notice any problems, please let us know so we can update things!

5 Likes

...And if you thought that was complicated, imaging writing it and having to do lots of meta-formatting. :smiley:

In fact, looking at the raw code for the post above is a good way to learn some things, if you want to get really advanced, so here it is in a text file:

Formatting_Tips_Opus_Forum.txt (11.1 KB)

(Text file updated: 01-Sep-2017.)

3 Likes

Tables can be added using html

column 1 column 2 column 3
dopus foo bar
resource foo bar
<table>
<thead>
<tr><th>column 1</th><th>column 2</th><th>column 3</th>
</thead>
<tbody>
<tr><td><a href="http://www.dopus.com">dopus</a></td><td>foo</td><td>bar</td></tr>
<tr><td><a href="http://resource.dopus.com">resource</a></td><td>foo</td><td>bar</td></tr>
</tbody>
</table>

Update as of 1.9.0 b4 tables can now also be created with markdown. Using HTML is still more flexible.

Example

Col A Col B Col C
A1 B1 C1
A2 B2 :smile:
| Col A | Col B | Col C|
|---|---|---|
| A1 | B1 | C1 |
| A2 | B2 | :smile: |

Table examples https://meta.discourse.org/t/create-a-table-using-markdown-on-your-discourse-forum/66544/15

Discourse uses the CommonMark
reference can be found here http://spec.commonmark.org/

1 Like