How to Write a Python Tutorial

Anyone can write an interactive Python tutorial here, in the same format as our own lessons. You write in Markdown, a simple way to format text, plus a few special blocks for runnable code and exercises. Everything you see on this page was made with the blocks described below.

How it works

1. Open Write a tutorial. The editor is on the left and a live preview on the right.
2. Give your tutorial a title, and optionally a one-line description.
3. Write. The preview updates as you type, and every code block in it really runs.
4. Click Publish. You get two links:
   • the public link to share with anyone;
   • a private edit link. It's the only way to change your tutorial later, so save it somewhere safe. There are no accounts, so we can't send it to you again.

Your draft is saved in your browser while you work, so closing the tab doesn't lose it.

Writing text

Leave a blank line between paragraphs. Use ## for the main sections and ### inside them. The title you type in the title box is the page's main heading, so don't repeat it with #.

Runnable examples

A code block marked python run becomes a small editor with a Run button. Readers can change the code and run it again:

```python run
name = "Ada"
print(f"Hello, {name}!")
```

That gives:

name = "Ada"
print(f"Hello, {name}!")

input() works too: readers type their answer below the output.

A block marked just python is shown with colours but can't be run. Use it for fragments that wouldn't work on their own:

total = price * quantity

Exercises

An exercise is a python exercise block with the starting code. Up to three optional blocks can follow it, in any order:

• python solution: the answer. Readers see a Show answer button.
• hint: a hint, written in Markdown. Add several hint blocks for hints that are revealed one at a time.
• output: the exact output a correct answer prints. When a reader runs their code, it's checked against this and they're told whether they got it right.

```python exercise
numbers = [4, 8, 15]

```

```python solution
numbers = [4, 8, 15]
print(sum(numbers))
```

```hint
There's a built-in function that adds up a list.
```

```hint
Try `sum(numbers)`.
```

```output
27
```

That gives:

numbers = [4, 8, 15]

Going deeper boxes

Optional extras, the kind of thing a curious reader enjoys but a beginner can skip, go in a collapsible box. It starts with ~~~deeper and a title, and ends with ~~~. Inside, you can use any Markdown, including runnable code:

~~~deeper Looping with an index
`enumerate()` gives you each item and its position:

```python run
for i, fruit in enumerate(["apple", "banana"], start=1):
    print(i, fruit)
```
~~~

That gives:

for i, fruit in enumerate(["apple", "banana"], start=1):
    print(i, fruit)

Note the tildes (~~~): they let the box contain ``` code blocks.

Notes, tips and warnings

Coloured boxes draw attention to something important. Start a quote with [!type] and, if you like, a title. The Note menu in the editor inserts them for you:

> [!info] Note
> Something worth knowing.

> [!success] Tip
> A tip or a good habit.

> [!warning] Careful with "w"
> Opening a file in write mode erases it.

> [!danger] Common mistake
> Forgetting the colon after `if`.

That gives:

Leave out the title to get the default one (Note, Tip, Warning or Danger). Use them sparingly: one or two per section is plenty.

Tables

Tables are handy for quick-reference summaries. Separate columns with | and put a |---|---| line under the header:

| Code | What it does |
|---|---|
| `len(items)` | Number of items |
| `sorted(items)` | A new sorted list |

Linking to our lessons

To point readers to one of the Learn Python lessons, use lesson: followed by the lesson's name. The editor's Lesson link menu inserts these for you:

See [Lists](lesson:lists) for more.

That gives: See Lists for more. Lesson links open in a new tab.

Tips for a great tutorial

• One idea per section. Explain it in a sentence or two, then show a runnable example.
• Keep examples short. Five to ten lines that print something are better than one long program.
• Let readers practise. End with two to four exercises, from easy to a little harder, each with a solution and hints.
• Finish with a summary: a short bullet list of the main points.
• Test everything. Run every example and solution in the preview before you publish.

Limits and rules

• A tutorial can be up to 100 KB of text, which is several times longer than our longest lesson. The counter at the top of the editor shows how much you've used. If you run out, split the tutorial into parts.
• Code runs in the reader's browser with Pyodide. Most of the standard library works. Files written by the code exist only until the page is closed, and there's no network access.
• HTML isn't allowed in tutorials; it's shown as plain text. Images from https:// links work: ![description](https://example.com/picture.png).
• Community tutorials aren't reviewed by online-python.com. We may remove anything that is spam, offensive or unlawful.