rattatwinko/markdownblog

Fork 0

Files

ZockerKatze 5ad73485ce rust parser working on local build. fix docker build

2025-06-24 10:23:34 +02:00

11 KiB

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

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

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.

Train of Thought for this Project and 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
partly / working on it	Rewrite the Markdown Parser in Rust ; This works for local Builds but in Docker does not work due to permission error

Happy Blogging! 🎉

"DEVELOPERS! DEVELOPERS! DEVELOPERS!" - Steve Ballmer

— Rattatwinko, 2025 Q3

11 KiB Raw Blame History