Markdown Explained: Writing That Becomes Any Format

Introduction

Every README on GitHub, every post on Dev.to and Hashnode (the platforms this blog distributes to), and most technical documentation is written in Markdown: plain text with a few simple marks for formatting. It was designed to be readable as-is — even before conversion — and to convert cleanly into HTML, PDF, slides, and more. If you write anything technical, Markdown is the format to learn first.

The syntax in one minute

Markdown's core is small enough to learn in a sitting:

# Heading 1
## Heading 2
**bold text** and *italic text*
- A bullet list item
- Another item
1. A numbered item
2. Another numbered item
[link text](https://example.com)
`inline code` and a fenced code block (shown in the draft file as a nested example)
```
a fenced code block
```

Headings, emphasis, lists, links, and code cover the vast majority of documents. Tables, images, and blockquotes extend it slightly, and "flavours" (GitHub Flavoured Markdown being the standard) add conveniences like task lists (a dash, brackets and a space, then "todo") and strikethrough — all still plain text, all still readable without a tool.

Why plain text wins for documentation

Markdown's power is what it is not: it is not a binary format (like a Word document) that only one program can open, and it is not a layout tool that breaks when a version changes. Plain text works in Git (the Git post) — diffs show exactly what changed, line by line — it works in every editor (including VS Code, from this batch's first post), and it converts to anything later. That is why documentation, notes, and blog posts converge on it: the content outlives the tool that created it.

The honest trade

Markdown is deliberately limited: precise page layout, complex tables, and footnotes vary by flavour or don't exist, and two renderers can display the same file slightly differently. For a polished book or a designed page, you need something richer. But for the documents developers actually write — READMEs, guides, notes, posts — its limits are a feature: fewer choices means faster writing and consistent results.

Takeaway

Markdown is plain text with minimal formatting marks, it converts to HTML and more, and it plays perfectly with Git and every editor. Learn its small syntax once, and you can write documentation, READMEs, and posts for the rest of your career.

Comments

Post a Comment

Popular posts from this blog

Swift Explained: Apple's Language for iPhone, Mac, and More

Introduction Swift is Apple's language for its platforms: iPhone, iPad, Mac, Apple Watch, and Apple TV. Introduced in 2014 to replace the older Objective-C, it was designed to be safe, fast, and — unusually for a systems language — genuinely pleasant to read and write. Even if you never ship an app, Swift teaches one idea every developer should understand: optionals. Optionals: saying "this might be missing" Most bugs in app development come from one cause: code assuming a value exists when it does not. Swift makes that assumption impossible to hide. A value that might be missing is wrapped in an Optional, and you must unwrap it before use. var nickname: String? = nil nickname = "Waqas" if let name = nickname { print("Hello, \(name)!") } else { print("No nickname set.") } String? means "a String, or nothing". The if let unwraps it safely: inside the block, name is guaranteed to exist. There is no way to accidentally us...
Read more

Flutter Explained: One Codebase, Every Screen

Introduction Flutter is Google's framework for building apps from a single codebase: write once in Dart, and ship to iOS, Android, web, Windows, macOS, and Linux. It powers apps from Google Pay to the New York Times crossword app. Its core idea is simple and radical: everything on screen is a widget, and the interface is rebuilt from data whenever that data changes. Everything is a widget In Flutter, there are no separate concepts for layout, styling, and controls — everything is a widget, nested inside other widgets like HTML elements, but in code: import 'package:flutter/material.dart'; class Greeting extends StatelessWidget { @override Widget build(BuildContext context) { return Center( child: Text( 'Hello, Sara!', style: TextStyle(fontSize: 24, color: Colors.teal), ), ); } } Center positions its child, Text displays words, TextStyle styles them — each a widget, composed by nesting. Layout widgets (like Row, Column, ...
Read more

Go Explained: Simple Code That Runs Fast

Introduction Go was built at Google for a specific frustration: large programs that were slow to build and hard to read. The answer was a language that is deliberately small — fewer features, but the right ones, done well. If you know one programming language already, Go will feel familiar within an hour. The interesting parts are not the syntax, but two ideas: goroutines and channels. Goroutines: cheap concurrency Most languages make running things at the same time feel heavy — threads, thread pools, and careful setup. A goroutine is Go's lightweight version: you start one by writing go in front of a function call. package main import ( "fmt" "time" ) func say(text string) { for i := 0; i < 3; i++ { fmt.Println(text) time.Sleep(100 * time.Millisecond) } } func main() { go say("hello") say("world") time.Sleep(500 * time.Millisecond) } The go say("hello") line does not wait — it st...
Read more