loctvl842
;
DevFolioCLIBlogDocumentationSEO

How to Post a Blog with DevFolio CLI

How to Post a Blog with DevFolio CLI

⚠️ Internal Use Only
This CLI is only for DevFolio team members. Do not run outside the project environment.

This guide has two parts:

  1. Technical steps for uploading and managing posts.
  2. Best practices for writing high-quality, SEO-optimized blog content.

1. Technical Guide: Posting a Blog

Step 1: Prepare Your Markdown File

Each blog post must start with frontmatter:

---
title: My Awesome Blog Post
slug: my-awesome-blog-post
excerpt: This post will teach you amazing things
tags: [Tutorial, Guide, Tips]
cover_url: https://example.com/cover.jpg
---

## Introduction

Write your content here using Markdown.

Frontmatter fields:

Field Description Default (if missing)
title Post title Derived from filename
slug URL slug Auto-generated from title
excerpt Short description First ~200 characters of text
tags Array or comma list [] (empty)
cover_url Cover image URL None

⚠️ Do NOT include an # H1 heading as your first line. The blog page already renders the title from frontmatter as <h1>, so your content should start at ## (H2) level for proper hierarchy and SEO.

Step 2: Upload the Post

uv run devfolio upload path/to/post.md

Optional custom slug:

uv run devfolio upload path/to/post.md --slug custom-slug

Behavior:

  • Always uploads the file to S3.
  • Creates a database record only if the slug does not exist (otherwise ISR will update content automatically).

Step 3: Manage Posts

List all posts:

uv run devfolio list

Delete a post by ID:

uv run devfolio delete <post-id>

2. Writing Good Blog Posts (Best Practices)

Posting is easy — writing a good post takes a bit more effort. Follow these tips:

Content Structure

  • Start with a clear intro (H2) – 1-2 sentences summarizing what readers will learn.
  • Use proper heading hierarchy – ## for sections, ### for subsections.
  • Keep paragraphs short – 3-4 lines max for readability.
  • Use lists and code blocks where helpful.
  • Add a conclusion or takeaway so readers leave with value.

SEO Optimization

  • Write a strong title – descriptive, keyword-rich, but concise (max ~70 characters).
  • Good excerpt – this shows up in search and previews. Make it compelling.
  • Use descriptive headings – helps search engines understand your content.
  • Add relevant tags – for better discoverability.
  • Include links – reference related blog posts or external resources when relevant.
  • Optimize images – meaningful cover_url, consider alt text if you embed images.

Writing Style

  • Prefer active voice and concise sentences.
  • Use consistent tone and Markdown formatting.
  • Break up text visually with headings, images, and lists.

Example Structure

---
title: 5 Tips for Writing Better Markdown
excerpt: Learn how to write cleaner, more readable Markdown that works well for blogs and documentation.
tags: [Markdown, Writing, Tips]
cover_url: https://example.com/cover.jpg
---

## Introduction

Markdown is simple, but good structure makes your posts shine. Here are five quick tips.

## Tip 1: Use Clear Headings

Good heading hierarchy improves readability and SEO.

## Tip 2: Keep Paragraphs Short

Readers skim. Keep blocks of text small and scannable.

...

## Conclusion

Following these tips will make your Markdown posts easier to read and better optimized for search engines.

✅ Pre-Publish Checklist

Before running devfolio upload, make sure:

  • Frontmatter is complete (title, excerpt, tags, cover_url if available).
  • Slug is correct and unique (or specify with --slug).
  • No duplicate # H1 heading in content — start with ##.
  • Excerpt is meaningful (not just the first random sentence).
  • Headings follow hierarchy (##, ###) for SEO.
  • Tags are relevant (help discoverability).
  • Links and images work (no broken URLs).
  • Content reads well (clear intro, conclusion, short paragraphs).
  • File is saved and committed to version control (if required).

Run:

uv run devfolio upload path/to/post.md

And you’re done. 🚀

Key Takeaways

  • Technical: Upload with devfolio upload, manage with list and delete.
  • Content: Use frontmatter, skip H1, structure content well, and think SEO.
  • Goal: Write posts that are easy to read and easy to find.

Happy blogging! 🚀