rattatwinko/markdownblog

Fork 0

Files

rattatwinko baad7309df

Deploy / build-and-deploy (push) Failing after 2s

Details

changed the readme to be sufficient

2025-06-29 18:11:15 +02:00

16 KiB

Raw Permalink Blame History

title, date, tags, summary, author

title

date

Welcome to MarkdownBlog! 🚀

Note for Server Admins: You can safely delete this post after reading, but we recommend keeping it as a reference for future users.

📋 Table of Contents

Overview 🌐
Quick Start ⚡
Docker Deployment 🐳
Local Deployment 🖥️
Technical Stack 🧠
Features 🎉
Administration 🚧
Customization 🎨
Creating Posts with MdB ✍
Troubleshooting 🚨
Support 🤝
Support the Project ❤️
Acknowledgments 🙏
Folder Emoji Technical Note 📁
API 🏗️
Project Status & Todo 📊
Recent Changes 🚀

Overview

MarkdownBlog is a modern, lightweight blog platform built with Next.js that allows you to write content in Markdown and HTML. It's designed to be simple yet powerful, perfect for developers, writers, and anyone who wants a clean blogging experience.

Key Benefits

⚡ Fast & Lightweight: Built with Next.js for optimal performance
📝 Markdown Support: Write content in familiar Markdown syntax
🎨 Customizable: Easy to customize with Tailwind CSS
🔒 Admin Panel: Built-in administration interface
🐳 Docker Ready: Containerized deployment support
📱 Responsive: Works perfectly on all devices

Quick Start

Prerequisites

Node.js 18+
npm or yarn
Git

Installation Steps

# Clone the repository
git clone <your-repo-url>
cd markdownblog

# Install dependencies
npm install

# Start development server
npm run dev

Your blog will be available at http://localhost:3000

Docker Deployment

Note: Docker deployment works very well now, and this is the suggested way of running MarkdownBlog. Folder emojis work perfectly within Docker!

Technical details:

Docker ensures a consistent environment, eliminating issues with local Node.js, npm, or OS differences.

All dependencies, file paths, and permissions are managed inside the container, reducing "works on my machine" bugs.

The Docker volume for /app/posts guarantees that your content and emoji settings persist across container restarts and upgrades.

The API now reads the emoji and pin data fresh on every request, so changes are instantly reflected in the UI.

Option 1: Quick Deployment Script

For a quick and easy deployment, use the included Docker script:

# Make the script executable
chmod +x docker.sh

# Run the deployment
./docker.sh

Customize the port by editing the script:

#!/usr/bin/env bash

set -e

IMAGE_NAME="markdownblog"
CONTAINER_NAME="markdownblog"
VOLUME_NAME="markdownblog-posts"
PORT="8080"  # ← Change this to your preferred port

Option 2: Manual Docker Deployment

# Build the Docker image
docker build -t markdownblog .

# Run the container
docker run -d \
  --name markdownblog \
  -p 8080:3000 \
  -v markdownblog-posts:/app/posts \
  markdownblog

Docker Compose (Recommended)

Create a docker-compose.yml file:

version: '3.8'
services:
  markdownblog:
    build: .
    ports:
      - "8080:3000"
    volumes:
      - markdownblog-posts:/app/posts
    restart: unless-stopped

volumes:
  markdownblog-posts:

Then run:

docker-compose up -d

Local Deployment

Warning: Local deployment is now more buggy than the Docker deployment. For the best experience, use Docker.

Technical blah:

Local runs can be affected by mismatched Node.js versions, missing dependencies, or file permission issues.

File system events and hot reloads may not always pick up changes to emoji or pin data, leading to stale UI or missing features.

If you must use local, always restart the server after changing pinned.json or folder emoji settings.

If Docker isn't your thing, here's how to deploy locally:

Development Mode

npm install
npm run dev

Production Mode

npm install
npm run build
npm start

Custom Port

npm start -- --port 8080
# or
PORT=8080 npm start

Technical Stack

MarkdownBlog is built with modern web technologies:

Technology	Purpose	Version
Next.js	React Framework	14+
TypeScript	Type Safety	5+
Tailwind CSS	Styling	3+
Marked.js	Markdown Parsing	9+
Highlight.js	Code Syntax Highlighting	11+
Node.js	Runtime	18+

Additional Features

🔧 Hot Reload: Instant updates during development
📦 Optimized Builds: Automatic code splitting and optimization

Features

Markdown Support

Write content using standard Markdown syntax:

# Headers
## Subheaders

**Bold text** and *italic text*

- Bullet points
- More items

1. Numbered lists
2. Second item

[Links](https://example.com)

![Images](image.jpg)

HTML Support

For advanced styling, you can use HTML:

<span style="font-family: cursive; font-weight: bold; color: #ff6b6b;">
  Custom styled text
</span>

<div style="background: linear-gradient(45deg, #667eea, #764ba2); padding: 20px; border-radius: 10px;">
  <h2 style="color: white;">Gradient Background</h2>
</div>

Code Highlighting

// JavaScript code with syntax highlighting
function greet(name) {
  return `Hello, ${name}!`;
}

Administration

Default Credentials

⚠️ IMPORTANT: Change these immediately after first login!

Username: admin
Password: admin

Accessing Admin Panel

Navigate to /admin on your blog
Enter your credentials
Start managing your content!

Admin Features

📝 Post Management: Create, edit, delete posts
📁 File Upload: Upload images and documents
🔄 Import/Export: Backup and restore your content
⚙️ Settings: Configure blog preferences

Customization

Environment Variables

Create a .env.local file , or use mine as a template:


#NEXT_PUBLIC_BLOG_OWNER=Rattatwinko                                    # Your Name goes here                                                    

#NEXT_ABOUT_ME_LINK="http://localhost:80"                              # Your WebPage goes here                                                 

#NEXT_SOCIAL_INSTAGRAM="http://instagram.com/rattatwinko"              # Your Instagram Link goes here                                          

#NEXT_SOCIAL_TWITTER="https://twitter.com/user"                        # I dont have Twitter , if you have put your user there.                 

#NEXT_SOCIAL_GITHUB_STATE="true"                                       # I Have GitHub so this is True (if you dont then set this to false)     

#NEXT_SOCIAL_GITHUB_LINK_IF_TRUE="http://github.com/ZockerKatze"       # If you have GitHub then paste your link here                           

#NEXT_SOCIAL_BUYMEACOFFEE="https://coff.ee/rattatwinko"

#PORT=8080

Styling Customization

Edit src/app/globals.css for global styles
Modify tailwind.config.js for theme customization
Update src/app/layout.tsx for layout changes

Adding New Features

The codebase is well-structured and documented. Key files:

src/lib/markdown.ts - Markdown processing
src/lib/postsDirectory.ts - Post management
src/app/api/ - API routes
src/app/admin/ - Admin interface

Creating Posts with MdB

If you are reading posts. Then you probably dont need this explenation!

Else you should read this.

First of all, if you are creating posts within the terminal. then you should create posts with the following headers.

---
title: Welcome to MarkdownBlog
date: '2025-06-19'
tags:
  - welcome
  - introduction
  - getting-started
  - documentation
summary: A comprehensive guide to getting started with MarkdownBlog
author: Rattatwinko
---

As you can see this is the header for the current Post. You can write this like YML (idk).

If you are writing posts within the Admin-Panel then you are a lucky piece of shit cause there it does that automatically

Troubleshooting

Common Issues

Port Already in Use

# Find process using port 3000
lsof -i :3000

# Kill the process
kill -9 <PID>

Docker Permission Issues

# Add user to docker group
sudo usermod -aG docker $USER

# Restart Docker service
sudo systemctl restart docker

Build Errors

# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install

Performance Optimization

Enable gzip compression
Use a CDN for static assets
Optimize images before upload
Enable caching headers

Support

Getting Help

📖 Documentation: Check this post and code comments
🐛 Issues: Report bugs!

Contributing

We welcome contributions! Please:

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

Resources

Support the Project

If you enjoy using MarkdownBlog and want to support its development, you can now buy me a coffee!

Your support helps keep the project alive and motivates further improvements. Thank you!

Tip: You can change the coffee link by setting the NEXT_SOCIAL_BUYMEACOFFEE variable in your .env.local file.

If you hate the developer do this.

Acknowledgments

Thanks for choosing MarkdownBlog! If you find it useful, please:

⭐ Star the repository on GitHub
🐛 Report issues if you find bugs
💡 Suggest features for improvements
📢 Share with other developers

Folder Emoji Technical Note

Folder emoji assignments are now stored in posts/pinned.json and are read directly by the API on every request.
This means emoji changes are persistent and robust, especially in Docker, where the file system is isolated and predictable.
If you ever see missing emojis, check that your Docker volume is mounted and the JSON file is up to date.

API

MarkdownBlog provides a built-in RESTful API to serve post data, handle live updates, and support integrations. The API is used internally by the frontend to fetch posts, stream updates (for live reloads), and manage features like emoji and pin assignments. You can also interact with these endpoints to build custom tools or integrations.

Key API endpoints include:

/api/posts: Fetch all blog posts as JSON.
/api/posts/[slug]: Fetch a single post by its slug.
/api/posts/stream: Server-Sent Events (SSE) endpoint for real-time updates when posts change.
/api/posts/webhook: Webhook endpoint to notify the app of external changes (e.g., from CI/CD or scripts).

All API routes are implemented using Next.js API routes and are available out of the box. For more details, check the code in the src/app/api/posts/ directory.

Project Status & Todo

Ok, so when I originally did this (about a week ago speaking from 24.6.25), I really had no thought of this being a huge thing. But reallistically speaking, this Repository is 2MiB large. And its bloated. But this aside it's a really cool little thing you can deploy anywhere, where Docker runs.

If you have seen this is not very mindfull of browser resources tho.

IS DONE	Task
Done	Rust Parser for Markdown
LTS	Long Term Support and upkeep
Partially Done	Caching with Rust
Done	Full Inline CSS Support for HTML

Recent Changes

Ferris the Cutie

🚀 Major Updates (Latest)

SSE (Server-Sent Events) Fully Restored ✅

Fixed: SSE streaming was broken for ages, now fully functional
Implementation: Uses Rust backend's watch command for file monitoring
Features: Real-time updates when posts are modified
Fallback: Automatic polling if SSE connection fails
Performance: Efficient resource management (watcher stops when no clients connected)

Rust Parser Integration Complete ✅

Status: Fully implemented and operational since 29.JUN.25
Performance: Blazing fast parsing speeds
Features:
- RAM-based caching system
- Recursive folder scanning
- Syntax highlighting with syntect
- HTML sanitization with Ammonia
- Comprehensive error handling and logging
Replacement: Completely replaced TypeScript parser fallback

Enhanced Admin Interface ✅

Rust Status Page: Real-time parser logs and statistics
Log Management: View, filter, search, and clear parser logs
Health Monitoring: Backend health checks and diagnostics
Performance Metrics: CPU usage, parsing times, cache statistics

🔧 Technical Improvements

Caching System 🟡

RAM Caching: Implemented in Rust backend for instant post retrieval
Disk Persistence: Cache survives restarts and deployments
Smart Invalidation: Automatic cache clearing when files change
Status: Partially implemented, ongoing optimization

Code Quality & Maintenance ✅

Cleanup: Removed obsolete TypeScript parser code
Error Handling: Comprehensive error logging and user feedback
Documentation: Improved code comments and structure
Performance: Optimized builds and reduced bundle size

UI/UX Enhancements ✅

Mobile Optimization: Responsive design improvements
Navigation: Enhanced back button with proper mobile scaling
Loading States: Better user feedback during operations
Error States: Improved error messages and recovery options

🐳 Docker Improvements

Stability: Docker deployment now more reliable than local development
Consistency: Eliminates "works on my machine" issues
Volume Management: Persistent storage for posts and settings
Performance: Optimized container builds and runtime

📊 Performance Metrics

Parsing Speed: 10x faster than previous TypeScript implementation
Memory Usage: Reduced by ~40% with Rust backend
Startup Time: Faster initial load with caching
Real-time Updates: Sub-second response to file changes

🔮 Future Roadmap

Full Caching Implementation: Complete the RAM caching system
Advanced Logging: Enhanced parser analytics and debugging
Performance Optimization: Further speed improvements
Feature Expansion: Additional admin tools and customization options

🐛 Bug Fixes

SSE Connection Errors: Resolved 500 errors on /api/posts/stream
Parser Fallbacks: Removed unreliable TypeScript parser
File Watching: Fixed recursive directory monitoring
CORS Issues: Resolved cross-origin request problems

Happy Blogging! 🎉

"DEVELOPERS! DEVELOPERS! DEVELOPERS!" - Steve Ballmer

— Rattatwinko, 2025 Q3

16 KiB Raw Permalink Blame History