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
• Troubleshooting
• Support

---

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

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

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                           

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

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

---

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

---

Happy Blogging! 🎉

"DEVELOPERS! DEVELOPERS! DEVELOPERS!" - Steve Ballmer

— Rattatwinko, 2025 Q3