You know the basics — headings, bold, links. If you’re still getting started, the markdown blogging guide covers everything from scratch. Already sold on the format? Read why markdown is the best choice for blogging.
Here are the tips that make your markdown blog posts clearer, more readable, and easier to write.
Don’t skip heading levels. Go H1 → H2 → H3. Search engines and screen readers use heading hierarchy to understand your content structure.
# Post Title (H1 — only one per post)
## Main Section (H2)
### Subsection (H3)
### Another Subsection (H3)
## Next Main Section (H2)Headings should tell scanners what they’ll learn. Put the key information first.
| Weak | Strong |
|---|---|
| A Look at Performance | Performance: 3x Faster Rendering |
| Some Thoughts on Testing | Testing Saves Time |
| Why This Matters | Portability Matters |
Three to four sentences per paragraph. On screens, dense text blocks are hard to scan. White space helps readers breathe.
A single-sentence paragraph is fine for emphasis.
Use bold for terms you want scanners to catch. Use italic for subtle emphasis, tone shifts, or introducing a term.
FolderPress uses **webhook-triggered sync** — meaning changes
appear in *seconds*, not minutes.Don’t overuse either. When everything is emphasized, nothing is.
Wrap file names, paths, commands, and code references in backticks:
Save your post as `hello-world.md` in the `posts/` folder.
Run `git status` to check for changes.This visually distinguishes technical terms from regular text and signals “this is a literal value.”
Don’t combine bold and italic unless you have a very good reason. Pick one.
Bad: ***This is important***
Good: **This is important**Screen readers announce link text out of context. Make it meaningful.
Bad: Click [here](url) to read more.
Good: Read the [custom domain setup guide](/custom-domain-setup).When a paragraph has many links, reference-style keeps the text clean:
FolderPress supports [Shiki][1] for code and [KaTeX][2] for math.
[1]: https://shiki.style
[2]: https://katex.orgThe link definitions can go at the bottom of your file, keeping your writing flow uninterrupted.
Alt text isn’t optional. It helps screen readers, shows when images fail to load, and improves SEO.
Bad: 
OK: 
Good: Describe what the image shows, not what it is.
Keep your Dropbox folder clean:
my-blog/
posts/
my-post.md
images/
my-post/
diagram.png
screenshot.jpg
Reference them with relative paths in your markdown.
Language identifiers enable syntax highlighting:
```python
def greet(name):
return f"Hello, {name}"
```Without the language identifier, you get monospace text without highlighting. FolderPress uses Shiki with 100+ supported languages.
| Language | Identifier |
|---|---|
| JavaScript | javascript or js |
| TypeScript | typescript or ts |
| Python | python or py |
| HTML | html |
| CSS | css |
| Bash/Shell | bash or sh |
| JSON | json |
| Markdown | markdown or md |
| SQL | sql |
| Go | go |
| Rust | rust |
If it’s less than a line, use inline code:
Set the `published_at` field in your frontmatter.Save fenced code blocks for multi-line examples.
Markdown tables work whether or not you align the pipes. But aligned tables are easier to edit:
Aligned (easier to read in your editor):
| Name | Role | Status |
|---------|-----------|----------|
| Alice | Writer | Active |
| Bob | Editor | Active |
Unaligned (works the same):
| Name | Role | Status |
|---|---|---|
| Alice | Writer | Active |
| Bob | Editor | Active |Most markdown editors have a table formatting shortcut. Use it.
Tables work best with short cell contents. If you’re writing paragraphs in table cells, switch to a heading + paragraph structure instead.
published_at and descriptionThe two most useful frontmatter fields:
---
published_at: 2026-01-15
description: "A short summary for search engines and social cards."
---published_at defaults to the current date when first synced — set it explicitly for backdated posts. description is auto-generated from your content (~155 characters of body text) if you don’t set it. Write a strong opening paragraph and the description takes care of itself, or override it when you want something specific for SEO and social previews.
Use the .draft.md convention to keep works-in-progress unpublished:
my-post.draft.md → Not published
my-post.md → Published
This is how FolderPress handles drafts — no “draft” toggle, no publish button. The filename is the state. Rename the file when you’re ready and it goes live on the next sync.
Don’t format while drafting. Get the ideas down in plain paragraphs, then add headings, lists, bold, and links in a second pass.
Most markdown editors have a preview mode. Check your formatting before removing .draft from the filename.
Pick a pattern for filenames and stick with it:
2026-02-15-why-i-write.md → date-prefixed
why-i-write.md → simple slug
The filename becomes the URL slug, so keep it lowercase, use hyphens, and make it descriptive.
On FolderPress, your folder structure is your URL structure. A file at posts/guides/getting-started.md becomes /guides/getting-started on your site. Organize your folders the way you’d want your URLs to read.
Ready to put these tips into practice? Start a markdown blog in under five minutes.