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.

#Structure Tips

#Use Heading Hierarchy

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)

#Front-Load Your Headings

Headings should tell scanners what they’ll learn. Put the key information first.

#Keep Paragraphs Short

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.

#Formatting Tips

#Bold for Scanning, Italic for Nuance

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.

#Use Inline Code for Technical Terms

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.”

#Avoid Nested Emphasis

Don’t combine bold and italic unless you have a very good reason. Pick one.

Bad:  ***This is important***
Good: **This is important**

#Link Tips

#Use Descriptive Link Text

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).

#Reference-Style Links for Readability

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.org

The link definitions can go at the bottom of your file, keeping your writing flow uninterrupted.

#Image Tips

#Always Write Alt Text

Alt text isn’t optional. It helps screen readers, shows when images fail to load, and improves SEO.

Bad:  ![](screenshot.png)
OK:   ![Screenshot](screenshot.png)
Good: ![FolderPress dashboard showing two sites](screenshot.png)

Describe what the image shows, not what it is.

#Organize Images in a Subfolder

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.

#Code Block Tips

#Always Specify the Language

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.

#Common Language Identifiers

#Use Inline Code for Short Snippets

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.

#Table Tips

#Align Your Pipes (Or Don’t)

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.

#Keep Tables Simple

Tables work best with short cell contents. If you’re writing paragraphs in table cells, switch to a heading + paragraph structure instead.

#Frontmatter Tips

#Use published_at and description

The 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.

#Writing Workflow Tips

#Draft in a Separate File

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.

#Write First, Format Later

Don’t format while drafting. Get the ideas down in plain paragraphs, then add headings, lists, bold, and links in a second pass.

#Preview Before Publishing

Most markdown editors have a preview mode. Check your formatting before removing .draft from the filename.

#Use a Consistent Naming Convention

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.