# The Markdown Guide Repository: A Jekyll Site That Documents Markdown Syntax

> mattcone/markdown-guide is the source behind markdownguide.org, a Jekyll static site whose content is CC-BY-SA-4.0 and whose templates are MIT. It is a reference to contribute to or self-host, not a parser or a library.

**mattcone/markdown-guide** — The comprehensive Markdown reference guide.

- Repository: https://github.com/mattcone/markdown-guide
- Website: https://www.markdownguide.org
- Stars: 4,109 · Forks: 718
- Language: HTML
- License: CC-BY-SA-4.0
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/mattcone-markdown-guide

## What the Markdown Guide repository actually contains

The project is the publishing pipeline behind markdownguide.org. Its README describes it as a comprehensive Markdown reference designed for both novices and experts, written because the author found existing references incomplete. That framing matters: the deliverable is documentation, not software you import.

The repository layout supports that reading. Directories named _basic-syntax, _extended-syntax, _getting-started and _tools hold the guide's content collections, while _layouts and _includes hold the templates that render them. The top level carries pages such as cheat-sheet.md, basic-syntax.md, extended-syntax.md, getting-started.md, hacks.md and book.md, plus _config.yml and a netlify.toml for deployment. A Rakefile and a Gemfile sit alongside a .ruby-version file. Nothing here parses Markdown for you; the site explains the syntax and lets a static generator turn that explanation into pages.

The audience is therefore narrower than the site's traffic suggests. Readers of markdownguide.org come for the cheat sheet and the syntax tables. Contributors come for the repository. If you are building an editor, a converter or a linter, this is the wrong dependency, and the README does not pretend otherwise.

## How the Jekyll content collections turn Markdown into the site

The mechanism is the standard Jekyll one. Underscore-prefixed directories are collections: _basic-syntax and _extended-syntax each hold the individual syntax topics, and _config.yml tells Jekyll how to build them. Layouts in _layouts wrap that content, partials in _includes get reused across pages, and _data holds structured values the templates read. The output is a static site.

A consequence of that design is that the guide is written in the very format it documents. Each syntax page is a Markdown file with front matter, so a contributor editing a table of delimiters is also exercising the syntax being described. That is elegant for a reference site and awkward for anyone who wants the prose in another system: the content is entangled with Jekyll's collection and layout conventions, not stored as neutral data.

The deployment side is visible in netlify.toml and redirects.conf, which suggests the production site is built on Netlify with redirect rules applied at the edge. The README does not document the build command used in production, so a self-hoster should treat the local serve step as the known-good path and treat the hosting configuration as a starting point to inspect rather than a documented procedure.

## Running the Markdown Guide locally with Bundler and Jekyll

The README gives a four-step local workflow and nothing more. Ruby must already be installed; the repository pins a version in .ruby-version, so check that file against your interpreter before installing gems. Then, from the repository root, install the dependencies declared in the Gemfile:

```bash
bundle install
```

With the gems in place, start the development server. Jekyll serves the generated site, and the README says to point a browser at http://127.0.0.1:4000/:

```bash
bundle exec jekyll serve
```

What you should see is the guide rendered locally, with your edits reflected after a rebuild. The README does not list a separate build command, does not describe incremental rebuild flags, and does not document how to change the port. If port 4000 is occupied, the README is silent on the fix, so consult Jekyll's own documentation rather than guessing at a flag here.

For content changes, the practical path is to edit the relevant file under _basic-syntax or _extended-syntax, preview it locally, and open a pull request, which the README explicitly welcomes. For adding an application to the tools directory, the README does not put the instructions in the repository: it links to a wiki page titled Markdown tool directory, and that is where the submission rules live.

## Two licences, and the line between them

This is the detail most likely to trip up a reuser. The README separates the project into two licensed halves. The content itself, meaning the guide's prose and syntax documentation, is under Creative Commons Attribution-ShareAlike 4.0 International, held in the LICENSE file. The underlying source code used to format and display that content is under the MIT licence, held in LICENSE-CODE.

The practical reading is that the Jekyll templates, includes and layout code can be reused with minimal obligation, while the explanatory text carries attribution and share-alike conditions. Share-alike is the part to think about before mirroring the guide into a commercial handbook or an internal wiki with restricted distribution. The repository does not offer a separate commercial licence, and the README does not discuss relicensing, so the CC-BY-SA-4.0 terms are the terms. This is a description of what the files say, not legal advice; if redistribution is central to your plan, have someone qualified read LICENSE and LICENSE-CODE.

## Where the Markdown Guide is the wrong tool

The repository does not parse, render, lint or convert Markdown. If your build step needs to turn a .md file into HTML, this project will not do it, and no amount of reading the syntax pages changes that. The guide describes behaviour; it does not implement it.

A second limitation is dialect coverage. Markdown has no single specification, and the site's own structure reflects that by splitting content into basic syntax and extended syntax. The extended pages describe features that many processors handle differently or not at all. The repository does not ship a conformance test suite, so it cannot tell you whether a given library matches what a page describes. For that you need the processor's own documentation or a test corpus.

A third issue is freshness. The last push to the repository was on 2026-07-21. That is recent enough that the project is not dormant, but the site documents a format whose implementations change independently. A page being current in the repository says nothing about whether your chosen parser supports the feature it describes.

## The Markdown Guide compared with a specification like CommonMark

The obvious alternative for anyone who needs authoritative syntax answers is the CommonMark specification, and the difference in approach is fundamental. CommonMark is a normative document with a formal definition and an accompanying test suite; implementations are checked against it, and disagreements are resolved by citing it. The Markdown Guide is explanatory and pedagogical. It organizes syntax into basic and extended categories, offers a cheat sheet, and aims at readers learning the format rather than at implementers settling an edge case.

That makes the two complementary rather than competing. If you are writing a parser, the specification is the reference you must satisfy. If you are teaching a colleague what a table looks like, the guide's pages are faster to read. The repository also maintains a tools directory, which the specification does not attempt; the README points contributors to a wiki page for adding applications. Note that the guide's extended syntax pages describe conventions that grew up around particular processors, so a reader should not treat them as guaranteed behaviour across every Markdown implementation.

## Maintenance, releases and what upgrading costs

There are no releases in the repository metadata, which fits a documentation site: changes arrive as commits and pull requests rather than versioned artifacts. The last push was on 2026-07-21, so the project is being touched, but there is no changelog to read and no version number to pin. Anyone depending on the content should track commits rather than wait for a tag.

The upgrade cost for a fork is mostly dependency drift. The Gemfile and Gemfile.lock pin the Jekyll stack, and .ruby-version pins the interpreter, so a fork left alone for a year will likely need a Ruby bump and a fresh bundle install before it builds. Because the content is Markdown files with front matter, merging upstream changes into a fork means resolving conflicts in prose and in collection metadata, which is more tedious than merging code and harder to validate automatically. The README offers no guidance on rebasing a fork or on handling upstream content changes, so plan on manual review of every merged page.

## Conclusion

Adopt this repository if you want to submit a correction to the syntax documentation, mirror the guide for an offline or internal audience under CC-BY-SA-4.0, or study how a Jekyll site organizes a large reference. Do not adopt it if you need a Markdown parser, a linter or a rendering library: the repository ships prose and templates, and the README points elsewhere for tooling. Before forking, verify two things: that Ruby and Bundler are available on your machine, since the README gives bundle install and bundle exec jekyll serve as the only local workflow, and that the CC-BY-SA-4.0 share-alike term fits how you intend to redistribute the content, because the MIT licence covers only the source code used to format and display it.

## FAQ

### What is the Markdown Guide used for?

It is a reference for the Markdown syntax, split into basic and extended topics, aimed at both novices and experts. The repository is the Jekyll source that publishes that reference at markdownguide.org.

### How hard is it to learn Markdown with the Markdown Guide?

The README describes the guide as designed for both novices and experts, and the site separates basic syntax from extended syntax so a beginner can start with the smaller set. The repository itself does not include a graded tutorial beyond the getting-started material.

### How can I learn the basics of Markdown from this project?

The repository has a basic-syntax.md page and a _basic-syntax collection holding the individual topics, plus a cheat-sheet.md for quick lookup. Reading those pages on the built site is the intended path; the README does not describe any interactive exercises.

### What is the Markdown Guide?

It is a comprehensive Markdown reference, according to its README, created because the author found existing references incomplete. The published site is markdownguide.org, and this repository is its source.

### Does the Markdown Guide cover Markdown in VS Code?

The repository includes a _tools directory and a tools.md page for a directory of Markdown applications, and the README points contributors to a wiki page about adding tools. The README does not document editor-specific configuration for VS Code or any other editor.

## Sources

- [Issues](https://github.com/mattcone/markdown-guide/issues)
- [License: CC-BY-SA-4.0](https://github.com/mattcone/markdown-guide/blob/master/LICENSE)
- [mattcone/markdown-guide on GitHub](https://github.com/mattcone/markdown-guide)
- [Project website](https://www.markdownguide.org)
- [README](https://github.com/mattcone/markdown-guide/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mattcone-markdown-guide