Markdown Basics
A student-friendly guide to creating .md files and writing simple, clean Markdown for notes,
README files, assignments, and project docs.
What a Markdown file is
A Markdown file is a plain text file that uses simple symbols for formatting. The filename usually ends in
.md, like README.md, notes.md, or week-1-summary.md.
- Plain text means you can open it in VS Code, Notepad, nano, Vim, or GitHub.
- Markdown is easy to read before and after formatting is applied.
- It is commonly used for project instructions, class notes, and software documentation.
Lesson 1: Create your first .md file
Name the file with a .md extension. Then add a title and a few lines of text.
In a file explorer
Create a new file named notes.md.
In VS Code
Use Ctrl + N, then save as notes.md.
In a terminal
Use a command like touch notes.md on macOS/Linux.
# My Notes This is my first Markdown file. I can use it for class notes and project ideas.Copied!
Lesson 2: Add headings
Use # symbols to create headings. More # symbols mean a smaller heading.
# Main Title ## Section Title ### Smaller Section
Main Title
Section Title
Smaller Section
Lesson 3: Bold, italic, and inline code
Use simple symbols to emphasize text or show code and filenames.
**bold text** *italic text* `README.md`
bold text
italic text
README.md
Lesson 4: Make lists
Use dashes for bullet lists and numbers for ordered steps.
## Shopping List - Notebook - Pencil - Charger ## Steps 1. Open VS Code 2. Create notes.md 3. Start typing
Shopping List
- Notebook
- Pencil
- Charger
Steps
- Open VS Code
- Create notes.md
- Start typing
Lesson 5: Add links and images
Links help readers jump to websites or other pages. Images can show screenshots or diagrams.
[Visit GitHub](https://github.com) Copied!
For local images, use the correct relative path from the Markdown file to the image file.
Lesson 6: Write code blocks
Use triple backticks to show larger code samples. You can also name the language for syntax highlighting.
```python
name = "Trevor"
print(f"Hello, {name}")
```
Copied!
Lesson 7: Useful extras
> This is a blockquote. - [x] Finish homework - [ ] Review notes | Name | Score | |------|-------| | Ana | 95 | | Jay | 88 |Copied!
| Feature | Why students use it |
|---|---|
| Blockquotes | Highlight an important idea, note, or quote. |
| Task lists | Track steps in an assignment or project. |
| Tables | Organize values, schedules, or comparison notes. |
Example: A simple class note file
This is the kind of file a student could actually turn into weekly notes.
# Web Development Notes ## Today - Learned what Markdown is - Created a file named `notes.md` - Practiced headings and lists ## Important commands ```bash git status git add notes.md git commit -m "Add class notes" ``` ## Reminder Study link syntax before next class.Copied!
Quick reference table
| Task | Markdown |
|---|---|
| Main heading | # Title |
| Bold text | **important** |
| Bullet list | - item |
| Numbered list | 1. step |
| Link | [GitHub](https://github.com) |
| Code block | ```js ... ``` |
Optional background
Why Markdown matters in school and tech
- It keeps your notes readable without using a heavy word processor.
- GitHub and many coding tools automatically render Markdown files nicely.
- README files, project docs, and study guides often use Markdown by default.
Related pages
Git Cheatsheet, PowerShell, and Vim