Opinionated tutorial publisher

Programming tutorials consist of three things. Text, images, and code. Text should be readable, images should be pretty, and code should have syntax highlighting. Sounds simple right? It wasn’t as simple as it should be, so I made this.

This page lets you easily make pages just like this one, but with your own content. Give markdown, get back pretty HTML.

If you already have a markdown file, you can upload it here. For more details or example markdown, keep reading.

Usually If you want to write a programming tutorial and share it with the world your options are:

Upload it to a site like Medium with dark users practices and give up control and let them bloat your content with trackers, paywalls, and dark patterns.
Spend a few hours or days yourself setting up something like Hugo with GitHub pages and trying to get the theme to work just right.
Use something super minimalistic but not to everyone’s aesthetic taste like https://bearblog.dev/

As a fourth option, you can use this Opinionated Tutorial Publisher in three steps.

Write your tutorial in Markdown
Run a curl command or upload your markdown on this page
Upload the resulting single HTML file anywhere you want

Your tutorial will look exactly like this one. It gets good lighthouse scores. It adds about 25KB of “bloat” on top of your markdown, mainly for syntax highlighting.

Write the tutorial

This is the hard part. If you’re stuck for inspiration, use the one below (meta, isn’t it?). Copy everything in the box to a file named ‘tut.md’ on your local machine. Or use your own markdown file. Note that the image title (in the [] is used as a caption too, so we apply some light formatting.

# How to write Hello World in Python

Step 1: write hello world in Python

```python
import sys # just to show off highlighting

def hello():
    print("hello")

if __name__ == "__main__":
    hello()
```

You can add images by linking to them on any image hosting site. For example, imgur:

![**Image 1:** *An example tutorial*](https://i.imgur.com/nw41l3j.png)

That's the tutorial.

Step 2: Run the following curl command

Don’t do this with anything private obviously

curl -F 'file=@tut.md' https://api.ritza.co/publishtutorial > tut.html

If you don’t like curl, upload your markdown file here

Step 3: Host your tutorial on the web

Hosting is pretty complicated, but it’s easier if you just want to host one HTML file. You can push it to GitHub pages, scp it to a VPS running Apache or nginx, ask your Internet Service Provider for a static hosting package, or use one of the many free hosting services online. You can put it in AWS S3, use Netlify, or Repl.it.

**Image 2:** *A preview of the HTML tutorial*

FAQ

Why would I use this instead of something else? You almost certainly should rather use a hosting platform with markdown support like Ghost or Hugo instead. This is if you can’t be bothered to set one up, but can be bothered to run one command to improve the aesthetics of your tutorial.

Why is it better than any other markdown to HTML compiler? You can use many online markdown to HTML compilers, but none of them did quite what I wanted by default in terms of text, code, and images.

Can I just build this myself? Yes! I’ll release the code soon. It uses https://newcss.net/ for minimal CSS, https://prismjs.com/ for syntax highlighting and https://pandoc.org/ for the markdown to HTML conversion with a pandoc filter to make the HTML output play nicely with prismjs.

Can I change the theme? No, this is an opinionated publisher. Think Python Black formatter for tutorial formatting. I’ll keep improving the output but it’ll never be configurable.

Can I at least change the title? Sure, just edit the HTML. By default, the first line with content is your title and the next two become the meta description

Why did you build this? I’m launching https://ritza.co to help companies produce and publish tutorials, and I wanted to use it myself.