This commit is contained in:
392
posts/welcome.md
392
posts/welcome.md
@@ -1,148 +1,354 @@
|
|||||||
---
|
---
|
||||||
title: Read Me . Markdown!
|
title: Welcome to MarkdownBlog
|
||||||
date: '2025-06-19'
|
date: '2025-06-19'
|
||||||
tags:
|
tags:
|
||||||
- welcome
|
- welcome
|
||||||
- introduction
|
- introduction
|
||||||
summary: Read Me Please
|
- getting-started
|
||||||
author: Rattatwinko's
|
- documentation
|
||||||
|
summary: A comprehensive guide to getting started with MarkdownBlog
|
||||||
|
author: Rattatwinko
|
||||||
---
|
---
|
||||||
|
|
||||||
# Welcome to the Blog
|
# 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)
|
||||||
|
- [Troubleshooting](#troubleshooting)
|
||||||
|
- [Support](#support)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## Overview
|
## Overview
|
||||||
|
|
||||||
- [Starting Things off!](#starting-things-off)
|
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.
|
||||||
- [Formatting](#formatting)
|
|
||||||
- [Some Technical Information](#some-technical-information)
|
|
||||||
- [Building](#building)
|
|
||||||
- [Administration](#administration)
|
|
||||||
- [Todo List for the Project](#todo)
|
|
||||||
- [Issues with the Project](#issues)
|
|
||||||
- [Changelog](#changelog)
|
|
||||||
- [Closing Statements](#closing-statements)
|
|
||||||
|
|
||||||
## Starting Things off!
|
### Key Benefits
|
||||||
|
- ⚡ **Fast & Lightweight**: Built with Next.js for optimal performance
|
||||||
This blog was built as a response to the lack of blogging systems that accept "human readable" formats editable in a terminal emulator.
|
- 📝 **Markdown Support**: Write content in familiar Markdown syntax
|
||||||
|
- 🎨 **Customizable**: Easy to customize with Tailwind CSS
|
||||||
**Prerequisites:**
|
- 🔒 **Admin Panel**: Built-in administration interface
|
||||||
- NPM
|
- 🐳 **Docker Ready**: Containerized deployment support
|
||||||
- Docker (optional)
|
- 📱 **Responsive**: Works perfectly on all devices
|
||||||
|
|
||||||
That's about it.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Formatting
|
## Quick Start
|
||||||
|
|
||||||
Standard Markdown is supported. HTML with some basic CSS too! External CSS files aren't supported. JavaScript files aren't supported either (and won't be in the future, as it's a safety risk).
|
### Prerequisites
|
||||||
|
- Node.js 18+
|
||||||
|
- npm or yarn
|
||||||
|
- Git
|
||||||
|
|
||||||
**This is _Markdown_!**
|
### Installation Steps
|
||||||
|
```bash
|
||||||
|
# Clone the repository
|
||||||
|
git clone <your-repo-url>
|
||||||
|
cd markdownblog
|
||||||
|
|
||||||
| Option | Description |
|
# Install dependencies
|
||||||
| ------ | ----------- |
|
npm install
|
||||||
| <span style="color:blue;">data</span> | Path to data files to supply the data that will be passed into templates. |
|
|
||||||
| engine | Engine to be used for processing templates. Handlebars is the default. |
|
|
||||||
| ext | Extension to be used for destination files. |
|
|
||||||
|
|
||||||
<p style="background-color:grey;color:white;font-style:italic;">If you noticed <span style="color: #5BCEFA; font-weight: bold;">data</span> was blue! This works due to the HTML / CSS / Markdown <span style="font-weight: bold; font-size: 1em; padding: 0.2em 0.4em; border-radius: 4px;"><span style="color: #5BCEFA;">T</span><span style="color: #F5A9B8;">r</span><span style="color: #FFFFFF;">a</span><span style="color: #F5A9B8;">n</span><span style="color: #5BCEFA;">s</span>piler</span>. This basically means you can embed HTML into your Markdown blog-styled posts, and it will interpret correctly!</p>
|
# Start development server
|
||||||
|
npm run dev
|
||||||
|
```
|
||||||
|
|
||||||
**HTML Example:**
|
Your blog will be available at `http://localhost:3000`
|
||||||
|
|
||||||
<p style="text-align:center;font-style:italic;font-weight:bold;font-size:2em;background-color:grey;font-family:cursive;color:white;">Hello from HTML</p>
|
---
|
||||||
|
|
||||||
Heres the fancy **source code** for the **interrested**:
|
## 🐳 Docker Deployment
|
||||||
|
|
||||||
|
### 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
|
||||||
|
|
||||||
|
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
|
```html
|
||||||
<p style="text-align:center;font-style:italic;font-weight:bold;font-size:2em;background-color:grey;font-family:cursive;color:white;">Hello from HTML</p>
|
<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
|
||||||
## Some Technical Information
|
// JavaScript code with syntax highlighting
|
||||||
|
function greet(name) {
|
||||||
For development, I used:
|
return `Hello, ${name}!`;
|
||||||
- Docker
|
}
|
||||||
- TypeScript
|
|
||||||
- Next.js
|
|
||||||
- Git (of course)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Building
|
|
||||||
|
|
||||||
If you are deploying this on your machine for whatever reason, please note:
|
|
||||||
- Docker building is fully implemented and supported.
|
|
||||||
- Docker will deploy this app to port 8080 (http://localhost:8080)
|
|
||||||
- If you run this with:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
npm install && npm run dev # or production (if you're fancy enough to deal with it)
|
|
||||||
```
|
```
|
||||||
|
|
||||||
- Note that the build times will take a while. Docker takes ages too, but once built it can recover stuff from the cache, so it's much faster after the first build.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Administration
|
## Administration
|
||||||
|
|
||||||
<p style="color:red;font-style:bolder;">Please set your name (or not) in @.env.local! Before deploying this to Docker!</p>
|
### Default Credentials
|
||||||
|
⚠️ **IMPORTANT**: Change these immediately after first login!
|
||||||
|
|
||||||
If you are an admin, then the default username and password are:
|
- **Username**: `admin`
|
||||||
|
- **Password**: `admin`
|
||||||
|
|
||||||
```
|
### Accessing Admin Panel
|
||||||
user: admin
|
1. Navigate to `/admin` on your blog
|
||||||
password: admin
|
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
|
||||||
|
|
||||||
|
#PORT=8080
|
||||||
```
|
```
|
||||||
|
|
||||||
> [!CAUTION]
|
### Styling Customization
|
||||||
> Change the administration password once the server is set up. This is really easy!
|
- Edit `src/app/globals.css` for global styles
|
||||||
> The server will store your password as a hash. So be careful of people getting that hash.
|
- 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
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
You can pin a post both in the UI and in the backend of the server.
|
## Troubleshooting
|
||||||
|
|
||||||
```sh
|
### Common Issues
|
||||||
/path/to/your/instance/posts/pinned.json
|
|
||||||
|
**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
|
||||||
|
|
||||||
## TODO
|
# Restart Docker service
|
||||||
|
sudo systemctl restart docker
|
||||||
|
```
|
||||||
|
|
||||||
| Status | Task |
|
**Build Errors**
|
||||||
|:---------------------------------------------:|:-------------------------------------------------:|
|
```bash
|
||||||
|<span style="color:green;text-align:center;">DONE</span>|Code Editor in Admin Panel with saving!|
|
# Clear cache and reinstall
|
||||||
|<span style="color:green;"> DONE! </span>| Exporting Tar of 'Posts/' Folder|
|
rm -rf node_modules package-lock.json
|
||||||
|<span style="color:green;"> DONE! </span>| Mobile Viewing of the Website|
|
npm install
|
||||||
|<span style="color:orange;"> TO BE DONE! | Refactoring of the Code (Removing Garbage-Code)
|
```
|
||||||
|
|
||||||
|
### Performance Optimization
|
||||||
|
- Enable gzip compression
|
||||||
|
- Use a CDN for static assets
|
||||||
|
- Optimize images before upload
|
||||||
|
- Enable caching headers
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Issues
|
## Support
|
||||||
|
|
||||||
If any issues pop up, please open a Gitea issue with **proper** error reports!
|
### 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/)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Changelog:
|
## Acknowledgments
|
||||||
|
|
||||||
- Via merging of branch **"mobile"**:
|
Thanks for choosing MarkdownBlog! If you find it useful, please:
|
||||||
- Will have support for mobile devices
|
|
||||||
- Scrolling will be "different" (auto header scroll trough links)
|
- ⭐ **Star the repository** on GitHub
|
||||||
- Styling will be responsive!
|
- 🐛 **Report issues** if you find bugs
|
||||||
|
- 💡 **Suggest features** for improvements
|
||||||
|
- 📢 **Share** with other developers
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Closing Statements
|
> **Happy Blogging!** 🎉
|
||||||
|
>
|
||||||
Developing of this Applet has been really fun! Thanks JavaScript for fucking my ass harder than , eh ... idk , im gay, i cant make jokes about this.
|
> *"DEVELOPERS! DEVELOPERS! DEVELOPERS!"* - Steve Ballmer
|
||||||
Yeah fuck JavaScript, TypeScript is better.
|
>
|
||||||
|
> <cite>— Rattatwinko, 2025 Q3</cite>
|
||||||
<q style="font-style:italic;">
|
|
||||||
- Thanks Ratta<b>twink</b>o ; 17.05.2025
|
|
||||||
</q>
|
|
||||||
<img src="https://upload.wikimedia.org/wikipedia/commons/4/48/Gay_Pride_Flag.svg" style="width:50px;height:50px;float:left;"/>
|
|
||||||
Reference in New Issue
Block a user