538 lines
16 KiB
Markdown
538 lines
16 KiB
Markdown
---
|
|
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
|
|
---
|
|
|
|
# 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 🌐](#overview)
|
|
- [Quick Start ⚡](#quick-start)
|
|
- [Docker Deployment 🐳](#docker-deployment)
|
|
- [Local Deployment 🖥️](#local-deployment)
|
|
- [Technical Stack 🧠](#technical-stack)
|
|
- [Features 🎉](#features)
|
|
- [Administration 🚧](#administration)
|
|
- [Customization 🎨](#customization)
|
|
- [Creating Posts with MdB ✍](#creating-posts-with-mdb)
|
|
- [Troubleshooting 🚨](#troubleshooting)
|
|
- [Support 🤝](#support)
|
|
- [Support the Project ❤️](#support-the-project)
|
|
- [Acknowledgments 🙏](#acknowledgments)
|
|
- [Folder Emoji Technical Note 📁](#folder-emoji-technical-note)
|
|
- [API 🏗️](#api)
|
|
- [Project Status & Todo 📊](#project-status--todo)
|
|
- [Recent Changes 🚀](#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
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# Make the script executable
|
|
chmod +x docker.sh
|
|
|
|
# Run the deployment
|
|
./docker.sh
|
|
```
|
|
|
|
**Customize the port** by editing the script:
|
|
```bash
|
|
#!/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
|
|
|
|
```bash
|
|
# 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:
|
|
```yaml
|
|
version: '3.8'
|
|
services:
|
|
markdownblog:
|
|
build: .
|
|
ports:
|
|
- "8080:3000"
|
|
volumes:
|
|
- markdownblog-posts:/app/posts
|
|
restart: unless-stopped
|
|
|
|
volumes:
|
|
markdownblog-posts:
|
|
```
|
|
|
|
Then run:
|
|
```bash
|
|
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
|
|
```bash
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
### Production Mode
|
|
```bash
|
|
npm install
|
|
npm run build
|
|
npm start
|
|
```
|
|
|
|
### Custom Port
|
|
```bash
|
|
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:
|
|
|
|
```markdown
|
|
# Headers
|
|
## Subheaders
|
|
|
|
**Bold text** and *italic text*
|
|
|
|
- Bullet points
|
|
- More items
|
|
|
|
1. Numbered lists
|
|
2. Second item
|
|
|
|
[Links](https://example.com)
|
|
|
|
|
|
```
|
|
|
|
### HTML Support
|
|
For advanced styling, you can use HTML:
|
|
|
|
```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
|
|
// 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:
|
|
|
|
```env
|
|
|
|
#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.
|
|
|
|
```Markdown
|
|
---
|
|
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**
|
|
```bash
|
|
# Find process using port 3000
|
|
lsof -i :3000
|
|
|
|
# Kill the process
|
|
kill -9 <PID>
|
|
```
|
|
|
|
**Docker Permission Issues**
|
|
```bash
|
|
# Add user to docker group
|
|
sudo usermod -aG docker $USER
|
|
|
|
# Restart Docker service
|
|
sudo systemctl restart docker
|
|
```
|
|
|
|
**Build Errors**
|
|
```bash
|
|
# 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](https://nextjs.org/docs)
|
|
- [Tailwind CSS Guide](https://tailwindcss.com/docs)
|
|
- [Markdown Guide](https://www.markdownguide.org/)
|
|
|
|
---
|
|
|
|
## Support the Project
|
|
|
|
If you enjoy using MarkdownBlog and want to support its development, you can now [buy me a coffee](https://coff.ee/rattatwinko)!
|
|
|
|
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.
|
|
|
|
|<span style="color:pink;">IS DONE</span>|Task|
|
|
|-------|----|
|
|
|<span style="color:green;">Done</span>|**Rust Parser for Markdown**|
|
|
|<span style="color:lightblue;">LTS</span>|_Long Term Support and upkeep_|
|
|
|<span style="color:lime;">Partially Done</span>|**Caching with Rust**|
|
|
|<span style="color:green;">Done</span>|Full Inline _CSS_ Support for **HTML**|
|
|
|
|
## Recent Changes
|
|
|
|
<img src="https://upload.wikimedia.org/wikipedia/commons/0/0f/Original_Ferris.svg" style="height:50px;width:90px;display:block;margin:0 auto;" alt="cute lil guy">
|
|
<p style="display:block;margin:0 auto;text-align:center;font-style:italic;font-weight:bold;">Ferris the Cutie</p>
|
|
<br />
|
|
|
|
### 🚀 **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
|
|
|
|
<br />
|
|
|
|
<!--Markdown Image :heart:-->
|
|
<img src="https://blog.cyon.ch/wp-content/uploads/2016/05/i-love-markdown.png" alt="I looooooove Markdown" style="display:block;margin:0 auto;">
|
|
|
|
|
|
> **Happy Blogging!** 🎉
|
|
>
|
|
> *"DEVELOPERS! DEVELOPERS! DEVELOPERS!"* - Steve Ballmer
|
|
>
|
|
> <cite>— Rattatwinko, 2025 Q3</cite>
|