Table of Contents

Code

To format text as code within a paragraph, `‌useBackticks()`‌.

To format text as code within a paragraph, useBackticks().

We try to be diligent about formatting all code items this way, even identifiers: “call the foo method, increment x.” This helps students distinguish text is literally code versus merely talking about code.

That distinction can get blurry, since the words that describe code can be the same words that appear in code. Some examples that are right on the judgement call line:

  • “The foo method returns a String.” ← OK: emphasizing the literal content of the code
  • “The foo method returns a string value.” ← Also OK: emphasizing the idea expressed in English (NB: lower case “string!”)
  • “Declare the function to be static.” ← OK: “static” is code
  • “Because the function is static, it cannot see instance variables.” ← Also OK: “static” is the name of a concept
Note that code suppresses normal Markdown and HTML parsing, so there is no need to escape markdown characters like `‌<‌this>`‌ or `‌**this**`‌.

Note that code suppresses normal Markdown and HTML parsing, so there is no need to escape markdown characters like <this> or **this**.

Note about special Coursage tags in inline code blocks

 
Coursage _will_ attempt to expand some of its special tags (such as `‌<‌‌highlight>`‌) even within a code block. If you need to show these as code, a workaround is to insert a “zero-width non-joiner“ character (Unicode 0x200c) into the tag.

Coursage will attempt to expand some of its special tags (such as <‌highlight>) even within a code block. If you need to show these as code, a workaround is to insert a “zero-width non-joiner“ character (Unicode 0x200c) into the tag.

If you need to show multiple lines of code, or want to visually emphasize a single line, use triple backticks:

```
void foo() {
    // code here
}
```

…or four-space indentation:

    void foo() {
        // code here
    }

Both the above produce this result:

void foo() {
    // code here
}

(Most docs use the first form because it plays better with lists, and is less prone to accidental over-indentation. Either form is fine if it works!)

Note that code blocks suppress line wrapping in the output, and instead scroll horizontally:

if (x < y) {
  return this || that || otherThing || yetAnotherThing || wow || tooLong || muchCode || why || why || why || why;  // Line that is far too long and probably needs a line break but hey, our doc system supports it
}

You can allow wrapping by adding {:.allow-wrap} immediately after a code block:

`‌`‌`‌
return this |‌|‌ that |‌|‌ otherThing |‌|‌ yetAnotherThing |‌|‌ wow |‌|‌ tooLong |‌|‌ muchCode |‌|‌ why |‌|‌ why |‌|‌ why |‌|‌ why;  // This long line will in fact wrap because we allowed it
`‌`‌`‌
{:.allow-wrap}

return this || that || otherThing || yetAnotherThing || wow || tooLong || muchCode || why || why || why || why;  // This long line will in fact wrap because we allowed it

Coursage applies syntax highlighting for Java to all code blocks by default. This can cause visually confusing results for blocks that are not Java:

You'll notice this is not Java code.

You can suppress highlighting for a block by marking it as plain text:

`‌`‌`‌txt
You'll notice this is not Java code.
`‌`‌`‌

You'll notice this is not Java code.

…and you can specify other languages, which the syntax highlighting library is likely to support!

`‌`‌`‌html
<‌ul>
  <‌li>Here is some <‌b>HTML<‌/b>.<‌/li>
<‌/ul>
`‌`‌`‌

<ul>
  <li>Here is some <b>HTML</b>.</li>
</ul>

The code syntax above suppresses standard Markdown syntax, so you can’t use Markdown to (for example) make code bold. Here the asterisks in the code come through as asterisks:

`‌`‌`‌
int x0 = **importantFunc()** + y;  // These asterisks do not become boldface
`‌`‌`‌

int x0 = **importantFunc()** + y;  // These asterisks do not become boldface

Code sections do not suppress Coursage’s custom extensions (such as hidden and highlighted code) until they are translated to HTML. This produces unexpected results:

`‌`‌`‌
int x1 = <‌highlight>importantFunc()<‌/highlight> + y;  // The highlight tag breaks!
`‌`‌`‌

int x1 = <span class='highlight' >importantFunc()</span> + y;  // The highlight tag breaks!

The solution to both of these problems is the same: (1) use a <pre> tag instead of Markdown code fences and (2) use raw HTML tags instead of Markdown styling:

<‌pre>
int x0 = <‌b>importantFunc()<‌/b> + y;  // The bold works!
int x1 = <‌highlight>importantFunc()<‌/highlight> + y;  // The highlight works!
<‌/pre>

int x0 = importantFunc() + y;  // The bold works!
int x1 = importantFunc() + y;  // The highlight works!

When using <pre>, if you want something that looks like an HTML tag to pass through as code, you will need to escape it using HTML entities:

`‌`‌`‌text
List item tag: <‌li>  // Inside a Markdown code block → no escaping needed
`‌`‌`‌
<‌pre>
List item tag: &lt;li&gt;  // Inside a pre tag → escaping needed
<‌/pre>

List item tag: <li>  // Inside a Markdown code block → no escaping needed

List item tag: <li>  // Inside a pre tag → escaping needed