Markdown Tutorial: the reference that deliberately stops at the basics

The premise is that nobody had written Markdown lessons for writers

The project's opening line explains its existence in the first person: the author could not find any useful Markdown lessons for writers on the internets, so he made one. That framing is the reason to read the site rather than skim it. Most Markdown documentation is written by and for developers, and it is written for people who already know what a repository is.

The stated audience is new users of Markdown, and the site is built around that. The lessons live in a lessons/ directory, with an index.md at the root and a conclusion.md alongside it, which is the shape of a course rather than a reference manual. The primary language of the repository is HTML, which is what a Jekyll site produces, and the licence is MIT with a LICENSE.txt file in the tree.

The homepage is www.markdowntutorial.com, and the CNAME file at the root of the repository is what binds that domain to the site when it is served through GitHub Pages. There is also a 404.html file, which matters more than it sounds: a Jekyll site with a CNAME and a hand-written 404 is a site that is being run as a public site with a domain people will land on and mistype.

The site is still being worked on. The last push to the repository was on 2026-06-29, and there are no GitHub releases, which is normal for a static site whose versions are the commits themselves.

Only the original syntax, and the omissions are argued rather than accidental

The editorial decision that defines the site is the decision to teach the original Markdown and nothing else.

The reasoning is given plainly. Everyone has their own Markdown flavour and preference, and since the site is meant for new users, the author chose to focus on the original specifics and leave out tables, definition lists and other addons, on the grounds that writers who have mastered the basics can explore newer syntaxes on their own.

Then there is a second layer of editing, which is more unusual. The project deliberately omits a lot of duplication in the original syntax, so the lessons do not mention that - and + are also valid list markers, or that * counts as italics just as __ counts as bold. The author is explicit that these omissions are intentional and also preferential, and gives the reason in the first person: he does not really like + for lists or __ as bold.

That is worth pausing on, because it is a teaching decision with a cost. A reader who arrives with no Markdown at all learns one canonical form of each construct, which is easier to hold in their head. A reader who arrives with a little Markdown, or who has seen a style guide somewhere else, learns a subset of the truth and may not know it is a subset. The site resolves this by being explicit rather than quiet about it, but the ambiguity lands on the reader rather than on the site.

So the site is not a complete Markdown reference and does not claim to be. It is a first course, and the docs of any serious Markdown implementation will be where the rest of the syntax lives.

A Jekyll site with an Ace editor for the practice panes

The tech stack is listed in the project documentation and it is worth reading because it explains what a reader experiences.

Jekyll handles the templating and the asset compilation. Ace provides the code editors, which is what makes the practice panes interactive: you edit Markdown in the browser and see the result next to it, rather than copying a snippet into a local editor. Marked does the Markdown conversion. Bootstrap provides the design and Font Awesome supplies the icons.

The repository layout follows the standard Jekyll convention, which tells you the site is a conventional static build rather than something custom. There is a _config.yml for the site configuration, a _layouts/ directory for the templates, a _data/ directory for the data files the templates read, and an _assets/ directory for the static assets. Then there is the content itself: index.md, conclusion.md and the lessons/ directory. The script/ directory holds the JavaScript behind the interactive pages.

A Gemfile and a Rakefile sit at the root, and a.ruby-version file pins the Ruby version the site is expected to build with. The.vscode/ directory is there for editors, and.github/ holds the workflow configuration.

One detail in the layout deserves attention: the top-level entries list eleven translation directories alongside the English content, with de, es, fr, jp, kr, nl, pl, pt-br, vi-vn, zh-cn and zh-tw. So the site is not an English-only tutorial with a community translating it afterwards. The translations are part of the repository, maintained alongside the English source, and a fork inherits all of them.

Running the site locally is two commands

The local development instructions are short, and they are the whole contribution story for anyone who wants to fix a typo or add a lesson.

After cloning the project you run:

# grabs the dependencies
bundle install
# builds and serves the site
jekyll serve

That is it. The first command resolves the Ruby dependencies from the Gemfile, and the second compiles the site and serves it locally with live reloading. The project's own summary of the result is two words: Et voila!

There is no separate asset build step, no frontend bundler and no content pipeline to learn. The .ruby-version file tells Bundler which Ruby to expect, and the Rakefile at the root is there for the routine tasks that come with a Jekyll repository.

For a content contribution the workflow is therefore: clone, bundle install, jekyll serve, edit a file in lessons/ or one of the translation directories, and look at the page. For a translation contribution the same applies to the corresponding directory. The interactive editors come from Ace through the template layer, so a change to how a lesson page is laid out is a change to the layout in _layouts/ rather than to every lesson.

Where Markdown Tutorial is the wrong tool

The first limit is the one the project states about itself. If you need a table, a definition list, footnotes, a task list or strikethrough, this site does not teach them and says so. A team standardising on GitHub Flavored Markdown will find the basics here useful and everything past the first page missing.

The second is the flavour risk that follows from that decision. Because the lessons present one canonical form of each construct, a reader who takes them as complete will not know that other renderers accept alternatives. In a team where one person writes - for lists and another writes +, the rendering will differ between the tools, and the tutorial will not have warned either of them. The site mitigates this by being explicit about the omissions, but a reader skimming a lesson is not reading the preamble.

The third is that it is a tutorial rather than a reference. There is no index of syntax, no exhaustive option tables and no comparison between implementations. That is the correct design for the stated audience and the wrong shape for a person who needs to look up one thing quickly.

The fourth is the ageing of the stack. The site is built on Jekyll with Marked for the Markdown conversion, and both of those have moved on since the repository was started. The pinned Ruby version in .ruby-version is what keeps the build reproducible, and it is also a signal that a fresh clone on a current system may need that version rather than the newest one. Nothing here suggests the project is unmaintained; the last push was on 2026-06-29. It suggests a small site whose dependencies are pinned rather than current.

The fifth is the licensing question, which is unusually clean here. The repository is MIT, and the logo and the site assets are part of that repository, so a fork can be reused under the same terms. That makes it one of the easier tutorial sites to adapt, which is also why the translations in the tree are a real asset to anyone expanding the audience.

Editorial conclusion

Markdown Tutorial is worth sending to a colleague who has to write documentation but has never touched Markdown, because the lessons are short, the order is deliberate and the site refuses to dilute the basics with extensions that different renderers disagree about. It is the wrong reference the moment you need a table, a definition list or a fenced code block with language hints. Before you point anyone at it, check the three things the project itself decides for you: that it teaches the original Markdown only, so anything beyond the basics is out of scope by design; that the lessons are also served in eleven translated directories, from de and es through zh-tw and vi-vn, which matters if your readers do not read English; and that the local workflow is a Jekyll site, so a fork needs bundle install and jekyll serve rather than a static file copy.

Frequently asked questions

Official sources

1. gjtorikian/markdowntutorial.com on GitHub
2. Issues
3. License: MIT
4. Project website
5. README