Markdown Quickstart

This tutorial is for people interested in contributing to JS Training Grounds.

JS Training Grounds is built using a documentation generator called Starlight. Starlight is built on top of Astro, and allows you to use Markdown to write your content. It also includes a plugin called Expressive Code that enables some really nice syntax highlighting features. This tutorial will show you how to write Markdown and the different Expressive Code features we use on JS Training Grounds to highlight our code snippets.

This tutorial assumes you’re already familiar with VS Code.

Intro

Markdown is a lightweight markup language. It lets you write your content in a simple format that can be converted into HTML. The file extension for Markdown files is .md or .markdown. On JS Training Grounds, we also use .mdx files. MDX is a superset of Markdown that allows you to use React components inside your Markdown files.

In the first half of this quickstart, you can toggle between the Markdown snippets and what they look like after being converted to HTML.

Stackblitz

If you prefer to work online, you can open the Starlight training ground repo on Stackblitz and start coding right away in your browser. You don’t have to run any of the npm commands if you use Stackblitz. (NOTE: This Stackblitz link works best in Chrome.)

Local Setup

If you prefer to work locally, you can follow these steps (you will need Node and npm installed).

First, visit the Starlight training ground repo. Press the green Code button and click Download ZIP. Unzip the file and then open it in your editor. Then, run this command in the terminal to install the packages listed in package.json.

npm install

Then run this command to start the dev server.

npm run dev

You should see something like this in your terminal.

 astro  v5.3.1 ready in 656 ms

┃ Local    http://localhost:4321/
┃ Network  use --host to expose

01:11:49 watching for file changes...

Visit localhost:4321 in your browser, then click on the Example Guide button.

In your editor, you’ll see several files. However, for now you’ll mainly be working in src/content/docs/guides/example.md.

Headings

You can use hashtags to create different headings. You can also create a level 1 heading by underlining the text with equals signs and a level 2 heading by underlining the text with dashes. On JS Training Grounds, we use hashtags for headings.

Markdown
HTML

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Heading 1
=========

Heading 2
---------

<h1>Heading 1</h1>
<h2>Heading 2</h2>
<h3>Heading 3</h3>
<h4>Heading 4</h4>
<h5>Heading 5</h5>
<h6>Heading 6</h6>

<h1>Heading 1</h1>

<h2>Heading 2</h2>

Make sure you follow the same rules for headings that you use for HTML.

NOTE: The level 1 heading in JS Training Grounds is actually created using the title attribute at the top of the page. This is a Starlight feature and not specific to Markdown. This means you should skip the level 1 heading and start with level 2 headings when adding content to JS Training Grounds.

---
title: Main Heading
---

Paragraph

You don’t need any special symbols to create a paragraph in Markdown. To create multiple paragraphs, separate them with a blank line.

Markdown
HTML

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod.

Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut.

<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod.</p>

<p>Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut.</p>

Unordered lists

You can use dashes or asterisks to create unordered lists. On JS Training Grounds, we use dashes.

Markdown
HTML

- Item
- Item
- Item

* Item
* Item
* Item

<ul>
  <li>Item</li>
  <li>Item</li>
  <li>Item</li>
</ul>

<ul>
  <li>Item</li>
  <li>Item</li>
  <li>Item</li>
</ul>

Ordered lists

You can use numbers with periods or parentheses to create ordered lists. On JS Training Grounds, we use periods.

Markdown
HTML

1. Item
2. Item
3. Item

1) Item
2) Item
3) Item

<ol>
  <li>Item</li>
  <li>Item</li>
  <li>Item</li>
</ol>

<ol>
  <li>Item</li>
  <li>Item</li>
  <li>Item</li>
</ol>

Italic text

You can use a single set of asterisks or underscores to make text italic. On JS Training Grounds, we use asterisks.

Markdown
HTML

*Italic*

_Italic_

This is what it would look like in a sentence:

This is some *italic* text.

<em>Italic<em>

<em>Italic<em>

This is what it would look like in a sentence:

<p>This is some <em>italic<em> text.</p>

Bold text

You can use 2 pairs of asterisks or underscores to make text bold. On JS Training Grounds, we use asterisks.

Markdown
HTML

**Bold**

__Bold__

This is what it would look like in a sentence:

This is some **bold** text.

<strong>Bold<strong>

<strong>Bold<strong>

This is what it would look like in a sentence:

This is some <strong>bold<strong> text.

Links

You can use square brackets and parentheses to create links. You can also use the second notation if you don’t want the URLs to clutter up your content. On JS Training Grounds, we use the first method.

Markdown
HTML

[Link](http://example.com/)

[Link][1]

Other stuff goes here...

[1]: http://example.com/

This is what it would look like in a sentence:

This is some [link](http://example.com/) text.

<a href="http://example.com/">Link</a>

<a href="http://example.com/">Link</a>

<p>Other stuff goes here...</p>

This is what it would look like in a sentence:

<p>This is some <a href="http://example.com/">link</a> text.</p>

Blockquotes

You can use the greater than sign to create a blockquote.

Markdown
HTML

> This is a blockquote.

<blockquote>
<p>This is a blockquote.</p>
</blockquote>

Horizontal rules

You can use 3 dashes or asterisks to create a horizontal rule. On JS Training Grounds, we use dashes.

Markdown
HTML

Lorem ipsum dolor.

---

Ut enim ad.

Lorem ipsum dolor.

***

Ut enim ad.

<p>Lorem ipsum dolor.</p>

<hr>

<p>Ut enim ad.</p>

<p>Lorem ipsum dolor.</p>

<hr>

<p>Ut enim ad.</p>

Inline code

Use backticks to create inline code.

Markdown
HTML

`Inline code`

This is what it would look like in a sentence:

This is some `inline code` text.

<code>Inline code</code>

This is what it would look like in a sentence:

<p>This is some <code>inline code</code> text.</p>

Code blocks

Use 3 backticks to open and close a code block.

Markdown
HTML

```
function greeting() {
  console.log("Hello World");
}
```

<pre><code>function greeting() {
  console.log("Hello World");
}</code></pre>

The snippet above will look like this when rendered in the browser:

1
function greeting() {
2
  console.log("Hello World");
3
}

Expressive Code

Syntax highlighting

To enable syntax highlighting, add the correct abbreviation after the top 3 backticks. Since this is a JavaScript snippet, we added js.

1
```js
2
function greeting() {
3
  console.log("Hello World");
4
}
5
```

1
function greeting() {
2
  console.log("Hello World");
3
}

Highlight words

To highlight a word or words, wrap the word(s) in double quotes after the abbreviation. In this example, we’re highlighting the word function.

1
```js "function"
2
// Javascript code with syntax highlighting.
3
function greeting() {
4
  console.log("Hello World");
5
}
6
```

1
// Javascript code with syntax highlighting.
2
function greeting() {
3
  console.log("Hello World");
4
}

You can highlight multiple words or phrases by adding more words or phrases in quotes. If the phrase you’re trying to highlight includes double quotes, you can include them inside the double quotes. In this example, we’re also highlighting "Hello World".

1
```js "function" ""Hello World""
2
// Javascript code with syntax highlighting.
3
function greeting() {
4
  console.log("Hello World");
5
}
6
```

1
// Javascript code with syntax highlighting.
2
function greeting() {
3
  console.log("Hello World");
4
}

Highlight a line

To highlight a line, wrap the line number you want to highlight in curly braces. In this example, we’re highlighting the first line.

1
```js {1}
2
// Javascript code with syntax highlighting.
3
function greeting() {
4
  console.log("Hello World");
5
}
6
```

1
// Javascript code with syntax highlighting.
2
function greeting() {
3
  console.log("Hello World");
4
}

Highlight multiple lines

You can highlight a range of lines by using a dash. In this example, we’re highlighting the first, second, and third lines.

1
```js {1-3}
2
// Javascript code with syntax highlighting.
3
function greeting() {
4
  console.log("Hello World");
5
}
6
```

1
// Javascript code with syntax highlighting.
2
function greeting() {
3
  console.log("Hello World");
4
}

You can highlight different groups of lines by separating them by a comma inside the curly braces. In this example, we’re highlighting the first and second lines as well as the fourth line.

1
```js {1-2, 4}
2
// Javascript code with syntax highlighting.
3
function greeting() {
4
  console.log("Hello World");
5
}
6
```

1
// Javascript code with syntax highlighting.
2
function greeting() {
3
  console.log("Hello World");
4
}

Highlight words and lines

You can highlight words and lines. Just separate them with a space after the abbreviation. In this example, we’re highlighting the same lines as before and also highlighting the words "Hello World".

1
```js {1-2, 4} ""Hello World""
2
// Javascript code with syntax highlighting.
3
function greeting() {
4
  console.log("Hello World");
5
}
6
```

1
// Javascript code with syntax highlighting.
2
function greeting() {
3
  console.log("Hello World");
4
}

File name

To add a file name to the top of the code snippet, add the title attribute to the top of the snippet with the filename. In this example, we’re adding title="HelloWorld.js".

1
```js title="HelloWorld.js" {1-2, 4} ""Hello World""
2
// Javascript code with syntax highlighting.
3
function greeting() {
4
  console.log("Hello World");
5
}
6
```

1
// Javascript code with syntax highlighting.
2
function greeting() {
3
  console.log("Hello World");
4
}

Collapse

To collapse multiple lines of code, add the collapse attribute with a range of lines. In this example, we’re collapsing lines 2 through 4.

1
```js title="HelloWorld.js" collapse={2-4}
2
// Javascript code with syntax highlighting.
3
function greeting() {
4
  console.log("Hello World");
5
}
6
```

1
// Javascript code with syntax highlighting.
3 collapsed lines
2
function greeting() {
3
  console.log("Hello World");
4
}

Hide line numbers

On JS Training Grounds, we turned on a setting so that line numbers show up on every code snippet by default. However, there are some situations where we do hide the line numbers on code snippets. To hide the line numbers, set the showLineNumbers attribute to false.

1
```js title="HelloWorld.js" showLineNumbers=false
2
// Javascript code with syntax highlighting.
3
function greeting() {
4
  console.log("Hello World");
5
}
6
```

// Javascript code with syntax highlighting.
function greeting() {
  console.log("Hello World");
}

Writing Style

The tutorials on this site should follow this pattern for each section:

Add a heading
Explain the main concept in 1 sentence
Explain in 1 sentence what code the user will write
Show the code snippet (and use the Expressive Code features listed above where appropriate)
Tell the user what they should see in the browser in 1 sentence

There are instances where you might have to use more than 1 sentence, but the goal is to be fairly terse. Also, you might have to repeat steps 3, 4, and 5 in a section depending on how complex the step is.

Here is an example from our Vue 3 tutorial:

style attribute

You can add a style attribute to an element just like in normal HTML.

Task: Add style="color: red;" to the h1 element.

1
<template>
2
  <h1 style="color: red;">Hello World</h1>
3
  <p>Lorem ipsum dolor...</p>
4
</template>

After saving, you should see the <h1> element turn red in the browser.

You can see that it has the heading, the various explanations, and the code snippet.

Formatting Rules

Here is a summary of all the rules to follow when writing Markdown for JS Training Grounds:

The main rule for our Markdown files is make sure you leave 1 blank line above and below an element. This goes for headings, paragraphs, code snippets, etc. You can view the raw Markdown in our GitHub repo to see examples of this.
Use hashtags for headings.
Use dashes for unordered lists.
Use numbers and periods for ordered lists.
Use 1 set of asterisks for marking text as italic.
Use 2 sets of asterisks for marking text as bold.
Use dashes for horizontal rules.