- Markdown allows you to quickly format plain text on GitHub and Reddit with a lightweight and easy-to-remember syntax.
- GitHub Flavored Markdown adds tables, to-do lists, alerts, footnotes, and advanced navigation between sections.
- Reddit uses Snoomark, a variant of Markdown similar to GitHub's but with features such as spoilers and a different way of handling images.
- Controlling headings, lists, quotes, code, links, and images dramatically improves the readability and effectiveness of any content on both platforms.
If you frequently write on GitHub or spend a lot of time on Reddit, mastering Markdown is one of those things that saves you hours and makes your life easier. It's a very lightweight markup language that allows you to quickly format plain text without struggling with menus or buttons, just with a few symbols placed in the right spots.
On GitHub, you'll find it everywhere: in repository README.md files , issues, pull requests, discussions, and even in your own profile. Reddit, on the other hand, uses a variant called Snoomark (Reddit-style Markdown) that inherits much of GitHub's syntax, with some unique features and limitations. Let's see, step by step and with plenty of examples, how to use Markdown on GitHub and Reddit quickly and without missing anything important.
What is Markdown and why is it so useful on GitHub and Reddit?
Markdown is a lightweight markup language designed to make plain text easy to read and write, while also allowing for effortless conversion to HTML. In practice, this means you can write normal text and add a few special characters to create headings, lists, tables, quotes, formatted code, links, or images.
On GitHub, the implementation used is GitHub Flavored Markdown (GFM), which extends the classic syntax with tables, to-do lists, advanced code highlighting, color support, alerts, and some allowed HTML tags. All of this is automatically rendered in .md files and in the platform's comment fields.
Reddit uses its own editor called Snoomark, a derivative of GFM. It shares much of the basic behavior (bold, italics, headings, lists, quotes, inline or block code, links, etc.), but has important peculiarities : for example, image support is more limited depending on the context, and it adds its own elements such as spoilers.
The beauty of all this is that, with a single syntax, you can write texts that look good on both GitHub and Reddit, adapting only a few details where each platform works differently. Learning the basic rules allows you to navigate both with ease without having to relearn anything from scratch.
Headings and content structure
One of the first things you'll use are headings , both on GitHub and Reddit. They help structure the text into sections and subsections.
In Markdown, a heading is created by preceding the text with one to six hash symbols: one for a level 1 heading, two for level 2, and so on up to level 6. For example, in a GitHub README.md file you might have something like: # Main Title , ## Section , ### Subsection , etc.
When GitHub finds two or more headings in a file, it automatically generates a table of contents accessible from the "Outline" icon at the top of the file. Each heading appears as a link that takes you directly to that section, which is great for long documents.
In addition, each heading becomes an internal anchor that you can link to with a URL snippet based on the title text. To generate that snippet, GitHub applies very specific rules: it converts letters to lowercase, replaces spaces with hyphens, removes punctuation and formatting characters (such as italics), trims excess spaces, and, if the result matches another previous heading, adds a numeric suffix (-1, -2, etc.) to make it unique.
This allows you to do things like place a ## Sample Section and then link to it from another point in the document with a link like (#sample-section) , or even link to sections with special characters in the title, since GitHub generates the snippet following those rules and makes it accessible with the same pattern.
Emphasis, highlighted text, and quotations
Markdown lets you highlight text using various forms of emphasis : bold, italics, strikethrough, subscript, superscript, or underline. On GitHub, the typical style table would look something like this, although we've summarized it here in different terms:
To make text bold , surround it with double asterisks or double underscores; for italics, use single asterisks or underscores; to strikethrough, use a double tilde (two tildes) on either side of the text. You can also combine nested bold and italics, use three asterisks to apply both to an entire section of text, or use HTML tags like `<b>` for subscripts and superscripts, and `<i>` for underlines.
GitHub also allows you to create blockquote quotes by placing a greater-than symbol (>) at the beginning of the line. The quoted text is displayed with a vertical bar to the left and in gray, making it stand out clearly. You can have multiple lines within the same blockquote, and even nest quotes by adding more > symbols at the beginning.
An advanced form of citation unique to GitHub is the alert or admonition . It uses the same blockquote syntax, but the first line includes a special marker to indicate the type of alert. For example, you can specify `alert` for useful information, `helpful tips`, `key data`, `urgent warnings`, and `warnings of risks or negative consequences`. GitHub displays each type with a different color and icon, helping to highlight critical information in your documentation.
Reddit also supports simple quotes with the same > symbol, although it lacks GitHub's rich ping system. Even so, it remains a very useful way to reply to someone by quoting part of their message without repeating it entirely.
Code highlighting, blocks, and colors
Both GitHub and Reddit allow you to highlight code snippets within text using backticks. For inline code, you enclose the word or command with a single backtick on each side. This is ideal for highlighting, for example, ` git status` within a sentence, making it clear that it's a command.
When you want a standalone block of code, Markdown uses three backticks: you write a line with three backticks, then the code on separate lines, and close with another three backticks. On GitHub, if you also specify the language right after the first backticks, syntax highlighting with colors and formatting specific to that language is applied.
GitHub also offers a specific feature for highlighting color values within backticks. If you type a color in hexadecimal, RGB, or HSL format between backticks, the platform includes a small color indicator next to the text. For example, if the background color in light mode is #ffffff and in dark mode is #000000, highlighting these codes allows you to quickly see which is which.
Regarding code and table display, GitHub lets you enable a fixed monospace font in all comment fields, making it easier to work with technical text. If you edit a lot of code snippets in your browser or in editors like Visual Studio Code , enabling this option makes alignment and readability much more consistent.
Reddit also supports code blocks with backticks, both inline and block, although their use there is focused more on small snippets or pseudocode than on long documentation like that of a repository.
Creating links in Markdown is very simple: you enclose the text to be displayed to the user in square brackets and the URL in parentheses. This works on both GitHub and Reddit, and can be enhanced with keyboard shortcuts on GitHub (for example, using key combinations to quickly convert selected text into a link).
GitHub adds some extra navigation-related features. Firstly, it allows you to link directly to headings using the snippet generation rules discussed earlier. Secondly, it supports relative links within the repository itself, which is crucial for technical documentation.
A relative link is one that is calculated using the current file as a reference. For example, if your README is in the project root and you want to link to a file docs/CONTRIBUTING.md, you simply write a link with the path docs/CONTRIBUTING.md. GitHub handles translating this relative link correctly in any branch you're on, preventing it from breaking when switching branches or cloning the repository.
The recommendation is to always use relative paths when navigating between files in the same repository, because absolute links may stop working in clones or forks. GitHub allows the use of standard operators like ./ or ../ and paths that begin with / relative to the project root.
If you want to create custom anchor points within a document beyond headings, you can use HTML tags with the `name` attribute. This allows you to place a target point in the middle of a paragraph or next to text that doesn't have its own title, and link to it using the same syntax as for automatically generated headings.
Images on GitHub: Markdown, HTML, and relative paths
On GitHub, images are generally embedded using the same syntax as links, but preceded by an exclamation mark. The alternative text (alt) is specified within square brackets, and the URL or path to the image is placed within parentheses. This alternative text is important for accessibility , as it's what screen readers will read and what will be displayed if the image fails to load.
Images can come from files within the repository itself or from external URLs. GitHub allows multiple relative path patterns for uploading images from different branches, other repositories, or even issues and comments, using suffixes like ?raw=true to force a direct file download when necessary.
In addition to standard Markdown syntax, GitHub supports the use of the HTML `<picture>` element. This element is especially useful for loading responsive images that change according to the user's theme preferences (light or dark). Using the `prefers-color-scheme` media query, you can define different image sources for each mode, and a default image for browsers that don't support this feature.
The typical pattern involves including within several elements with its media and srcset attributes, and finally a Using the alt attribute and a generic URL, users in dark mode see an adapted image, while those in light mode receive a different one, without having to duplicate content in the README file.
GitHub also supports HTML comments in Markdown files, allowing you to add invisible reminders to the reader, for example to remind them to update an image section or add new examples later.
Tables, fold-out sections, and content separation
One of the most useful improvements in GitHub Flavored Markdown is its table support . You can organize data into rows and columns using vertical bars to separate cells and a row of dashes to mark the header. It's also possible to align columns to the right, left, or center using a colon in the separator row.
Tables are very useful for presenting lists of programming languages, frameworks used, planned tasks, feature comparisons, or any other information that benefits from a matrix structure. GitHub renders these tables with a clean and readable style.
To keep a long README organized, you can use the HTML tag `<details>` to create collapsible sections. These sections display a summary within the `<summary>` tag and allow the user to expand or collapse additional content as needed. It's common practice to enclose tables or blocks of secondary information within `<details>` to avoid overwhelming the user at first glance.
If you want the section to appear expanded by default, simply add the open attribute to This technique is very practical for grouping rankings, long lists, or content that is not essential for a first reading but is convenient to have accessible.
Another simple tool for organizing information is the horizontal rule. It is created by writing three or more dashes on a line and serves to draw a dividing line between sections, allowing you to clearly separate, for example, a descriptive section from a section of references or additional notes.
These rules can be combined with end-of-document quotes to highlight inspirational phrases, reminders, or key messages. A typical example would be placing a motivational quote at the end of your profile README, formatted with a block quote after a separator line.
Hidden comments and format control
GitHub lets you insert HTML comments within Markdown using the syntax <!-- comment -->. Anything you put inside that comment won't be displayed in the rendered content, but it will be visible in the source code, making it ideal for internal notes or to-dos.
For example, in a profile README you can add a comment that says something like you need to expand the "About me" section later or that you need to review a table of obsolete technologies, without anyone visiting the profile seeing it directly.
Another useful feature is escaping characters that would normally be interpreted as Markdown. If you need to display asterisks, hash symbols, or other symbols literally without them being formatted, simply precede each one with a backslash. This allows you, for example, to write expressions that include list symbols without converting them into actual lists.
When you view a markup file on GitHub, you have the option to toggle between the rendered view and the source code with a button at the top (or open it in editors like Brackets ). Disabling Markdown interpretation lets you access typical code view features like linking specific lines , which is very useful when you want to highlight an exact section of a README or any .md file.
Finally, remember that GitHub handles line breaks differently in comments (issues, PRs, etc.) and in .md files. In comments, line breaks are respected directly, while in Markdown files you need to add two spaces at the end of the line, a backslash, or a period. to force the jump within the same paragraph.
Lists, nested lists, and to-do lists
Lists are one of the most commonly used elements in Markdown, both on GitHub and Reddit. You can create unordered lists by preceding each list item with a hyphen, asterisk, or plus sign. All of these markers render similarly to bullet points.
To generate ordered lists , number each line with a number followed by a period and a space. While the order of the numbers doesn't have to be perfect (GitHub usually recalculates it), it's a good idea to maintain consistent numbering to keep the source code readable.
Nested lists are created simply by indenting the items below them. In monospaced editors like Sublime Text , you just need to visually align the nested list markers below the first character of the text in the parent item. In contexts like the GitHub comment editor, where the font isn't monospaced, you should count how many characters are before the text and use that number of spaces for the indentation.
You can also build multiple levels of nesting, as long as you maintain consistency in the number of spaces. For very complex lists, this system requires a bit of practice, but once you get the hang of it, it's very quick to apply.
GitHub also offers task lists , which are very useful for issues, pull requests, and documentation. These are created by preceding the list with a hyphen, a space, and a pair of square brackets with a space or an "x" inside: one for pending tasks and one for completed tasks. These lists are rendered with checkboxes that can be selected or deselected from the interface.
If the text of a to-do list item begins with parentheses, it must be escaped with a backslash to avoid confusion in the parser. It's a small detail, but important when writing descriptions that begin with something like "(Optional)" or similar.
Mentions, references, and emojis on GitHub
One of the advantages of writing in Markdown on GitHub is the ability to use direct mentions of users and teams on the platform. You simply type @ followed by the username or team name, and GitHub sends a notification to that account, drawing their attention to the conversation.
When you type the @ symbol, GitHub displays a list of users and teams associated with the repository or thread, and you can filter this list as you type. Use the arrow keys and press Enter or Tab to accept the suggestions. For teams, use the format @organization/team-name, and all team members will be subscribed to the thread.
In addition to mentions, GitHub makes it easy to reference issues and pull requests simply by typing # followed by a number or part of the title. A list of suggested results appears, which you can complete in the same way as with mentions. This greatly speeds up navigation between related conversations.
If your repository has custom autolinked references configured, certain external notations (such as JIRA or Zendesk ticket IDs) may also be automatically converted into short links. This setting requires administrative privileges, but once enabled, it allows for cross-system data sharing with minimal effort.
Finally, GitHub supports emojis via code: type a colon, followed by the emoji name, and end with another colon. As you begin typing, a list of suggestions appears, which you can accept with Tab or Enter. Incorporating emojis into your comments helps give them a more human touch, as long as you don't overuse them in formal documentation.
Footnotes and advanced content
GitHub also supports footnotes using a bracket-based syntax and an identifier with a caret character. At the point where you want the reference, you insert something like `<footnote>`, and at the end of the document, you define the text of that footnote with the same tag, followed by a colon and the content.
Footnotes can span multiple lines, and to force line breaks within a footnote, double spaces are used at the end of the line, just as in the main body of the Markdown. When rendering, GitHub displays a superscript on the text and a list of footnotes at the end, with backlinks to navigate between references and footnotes.
Another advanced feature offered by GitHub is the previously mentioned alerts (NOTE, TIP, IMPORTANT, WARNING, and CAUTION). It's advisable to use them only when truly necessary and avoid chaining too many together to prevent overwhelming the reader. They cannot be nested within other complex elements, so careful planning is essential for their placement.
Finally, you can ask GitHub to temporarily hide sections of rendered Markdown by wrapping them in HTML comments, or to ignore the processing of certain characters with backslashes. This is especially useful when you're documenting Markdown syntax itself and need to show examples as is, without interpretation.
Markdown on Reddit: Snoomark and editing mode
Reddit is a discussion platform where almost any topic is welcome, organized into subreddits. In terms of formatting, it offers two editors: one for rich text that's more visual, and another for plain text based on Markdown. If you want to work quickly and have fine control over the result, you'll want to use the Markdown option.
By default, Reddit usually activates the rich text editor, so to switch to markup mode you have to click the Markdown mode option within the text box of a post or comment. From there, you can use Snoomark syntax directly.
If you prefer the Markdown editor to always load, go to your user settings, enter the Feed Settings section, and enable the "Default to Markdown" option . This way, the Markdown editor will open automatically every time you start writing a post or comment, without you having to change it manually.
Reddit supports most basic and advanced Markdown features: headings, bold and italics, lists, quotes, code blocks, links, and some of its own extras like spoilers. However, it has significant shortcomings compared to GitHub, especially in image handling , which is highly dependent on context and the type of editor.
Syntax supported by Reddit and spoilers
The Snoomark variant used by Reddit includes many elements in common with GitHub, so if you're already proficient in Markdown for repositories, transferring that knowledge to the Reddit environment is quite straightforward. You can use headings to structure long posts, numbered or bulleted lists, quotes to reply to other users, and code blocks when you want to display commands or technical snippets.
One of the notable differences is how Reddit handles images . Although in many cases images are uploaded through the graphical interface and not directly with Markdown syntax, the engine that processes the text content is still Snoomark, so the formatting surrounding those images is indeed based on Markdown.
Reddit, on the other hand, adds extra features not included in the standard specification, such as spoilers. These allow text to be hidden behind a layer that the user can reveal with a click. Technically, when Reddit processes a spoiler, it transforms it into a combination of HTML, CSS classes, and platform-specific JavaScript.
The resulting HTML representation of a spoiler includes handlers that control when to show or hide the content, and while theoretically something similar could be written with plain HTML, on Reddit it depends on its internal implementation. The important thing for you as a user is that, when writing, you only need to use the specific spoiler syntax provided by the editor, and Snoomark takes care of translating it into the appropriate structure.
In short, Snoomark inherits many behaviors from GitHub Flavored Markdown, but geared towards the needs of a discussion community rather than project documentation. Even so, the core remains the same: plain text with simple symbols transformed into structured and readable content.
Mastering Markdown syntax on GitHub and Reddit makes writing technical documentation, opening well-explained issues, leaving clear comments on pull requests, and participating in Reddit discussions much more efficient. With a few key rules—headings, emphasis, lists, quotes, code blocks, links, images, and specific tricks like tables, collapsible details, alerts, footnotes, and spoilers—you can go from writing bland messages to creating clean, scannable, and professional content without clicking a single mouse button.
