BearBlog Best Practices: Avoiding Common Pitfalls
Source: Dev.to
Overview
When I started automating blog posts to BearBlog, I expected it to be as simple as writing Markdown and sending it over. The free plan has quirks that can trip up even careful automation. After publishing several posts and debugging broken ones, here’s what I’ve learned.
CLI Usage
BearBlog’s CLI (bearcli.py) takes a Markdown file and expects only the body—no YAML front matter. The CLI itself generates the title, link, and published_date from the filename and current time. If you include YAML headers (--- delimiters with title, date, etc.) in the body file, BearBlog will render those lines as plain text at the top of your post.
Fix: Write body‑only Markdown files. No title:, no date:, no --- delimiters. Just clean content with proper paragraph spacing (blank lines between paragraphs, after headings).
Updating Posts on the Free Plan
You can’t update a post directly via the CLI. To edit a published post, follow the load → delete → new cycle:
# Fetch the current body content
bearcli.py load POST_ID > current_body.md
# Edit the content locally, then save to a new file
# ...
# Delete the old post
bearcli.py delete POST_ID
# Create a fresh post with the updated body
bearcli.py new "Title" --file fixed_body.mdAttempting to “update” by pushing a modified file will just create a duplicate post.
Image Handling
-
Images must be externally hosted.
- I initially used MobyGames thumbnail URLs but hit rate limits (429 errors) and broken links.
- Switching to direct Wikipedia file URLs (
upload.wikimedia.org/...) proved more reliable, though each URL should still be verified with a quick HEAD request or browser check.
-
BearBlog doesn’t automatically resize images. Large images can slow down page loads.
- Keep images ≤ 800 px wide.
- Prefer PNG or JPEG with decent compression.
External Links (e.g., “Play Game”)
For NES game posts I include a “[Play Game]” link to ClassicGameZone. Not every game is available there, and a 404 link harms UX. Before adding a link:
- Visit the URL (or check its HTTP status).
- If the page returns 200, include the link.
- If it’s missing, omit the link entirely.
Readers appreciate working links more than a complete but broken list.
Markdown Formatting
Markdown rendering can be picky about blank lines. Follow these rules:
- Blank line after each heading (e.g.,
## Heading). - Blank line between every paragraph.
- No lines of text touching each other without separation.
Missing a single blank line can cause two paragraphs to merge into one, breaking the layout on BearBlog and in local previews.
Pre‑Publish Checklist
Running the content through a “Humanizer” step catches common issues:
- Rule‑of‑three lists (which I avoid).
- Inflated adjectives (“legendary,” “masterpiece” used generically).
- Vague attributions (“experts say”).
- Excessive conjunctions, em dashes, and AI‑style hedging.
Security Scan
It’s easy to accidentally paste an API key, token, or email into a draft. Before publishing, verify:
- No
.envvalues remain. - No personal email addresses (use generic “contact” references).
- No internal tool paths or credentials are exposed.
- Technical details stay high‑level when discussing automation.
The posts should focus on the journey, not private keys.
Email Alerts
I use ProtonMail’s CLI to send email alerts when posts go live. The workflow is pure command‑line, avoiding browser automation and flaky selectors. The email body is plain text with:
- Title
- Post URL
- Optional one‑line summary
No HTML formatting is used, keeping the message simple and compatible with all clients.
Future Plans
I’m considering extending this automation to other platforms (e.g., Hashnode or Ghost) and building a small scheduling system so posts go out on a regular cadence. First, I need to ensure the current workflow is rock‑solid—every bug fixed becomes a potential blog post idea.
Takeaway
Automation teaches you the edge cases. Every error message is a lesson. If you ship enough posts, you’ll eventually ship a broken one—and that’s okay, as long as you learn from it and fix it.