markdownblog/posts/welcome.md

title, date, tags, summary, author

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

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 Emojis 🇦🇹
• API 🏗️
• ToT, and 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

1. Navigate to /admin on your blog
2. Enter your credentials
3. 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:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

Resources

• Next.js Documentation
• Tailwind CSS Guide
• Markdown Guide

---

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

Caching:

Recently the Rust Parser recived a update which introduced Caching using RAM. This is not yet fully implemented, but it is in the works.

Recursive Folder-Scanning via Rust:

The Rust Parser was not implemented fully (28.JUN.2025). BUT, I can proudly state that since 29.JUN.25 The Rust Parser is parsing with ease and with BLAZING SPEEDS

Fixed SSE CORS Connection:

Since Ages the SSE Streaming was broken, now its fixed (see @src/app/api/posts/stream/route.ts). This works fine, needs some work still.

Happy Blogging! 🎉

"DEVELOPERS! DEVELOPERS! DEVELOPERS!" - Steve Ballmer

— Rattatwinko, 2025 Q3