From 95ccb2b91603759bc732544a96dae52fcd09c317 Mon Sep 17 00:00:00 2001 From: rattatwinko Date: Sun, 22 Jun 2025 15:19:20 +0200 Subject: [PATCH] welcum --- posts/welcome.md | 392 ++++++++++++++++++++++++++++++++++++----------- 1 file changed, 299 insertions(+), 93 deletions(-) diff --git a/posts/welcome.md b/posts/welcome.md index de9268d..576b415 100644 --- a/posts/welcome.md +++ b/posts/welcome.md @@ -1,148 +1,354 @@ --- -title: Read Me . Markdown! +title: Welcome to MarkdownBlog date: '2025-06-19' tags: - welcome - introduction -summary: Read Me Please -author: Rattatwinko's + - getting-started + - 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 -- [Starting Things off!](#starting-things-off) -- [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) +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. -## Starting Things off! - -This blog was built as a response to the lack of blogging systems that accept "human readable" formats editable in a terminal emulator. - -**Prerequisites:** -- NPM -- Docker (optional) - -That's about it. +### 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 --- -## 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 +cd markdownblog -| Option | Description | -| ------ | ----------- | -| data | 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. | +# Install dependencies +npm install -

If you noticed data was blue! This works due to the HTML / CSS / Markdown Transpiler. This basically means you can embed HTML into your Markdown blog-styled posts, and it will interpret correctly!

+# Start development server +npm run dev +``` -**HTML Example:** +Your blog will be available at `http://localhost:3000` -

Hello from HTML

+--- -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) + +![Images](image.jpg) +``` + +### HTML Support +For advanced styling, you can use HTML: ```html -

Hello from HTML

+ + Custom styled text + + +
+

Gradient Background

+
``` ---- - -## Some Technical Information - -For development, I used: -- 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) +### Code Highlighting +```javascript +// JavaScript code with syntax highlighting +function greet(name) { + return `Hello, ${name}!`; +} ``` -- 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 -

Please set your name (or not) in @.env.local! Before deploying this to Docker!

+### 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` -``` -user: 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 + +#PORT=8080 ``` -> [!CAUTION] -> Change the administration password once the server is set up. This is really easy! -> The server will store your password as a hash. So be careful of people getting that hash. +### 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 --- -You can pin a post both in the UI and in the backend of the server. +## Troubleshooting -```sh -/path/to/your/instance/posts/pinned.json +### Common Issues + +**Port Already in Use** +```bash +# Find process using port 3000 +lsof -i :3000 + +# Kill the process +kill -9 ``` ---- +**Docker Permission Issues** +```bash +# Add user to docker group +sudo usermod -aG docker $USER -## TODO +# Restart Docker service +sudo systemctl restart docker +``` -| Status | Task | -|:---------------------------------------------:|:-------------------------------------------------:| -|DONE|Code Editor in Admin Panel with saving!| -| DONE! | Exporting Tar of 'Posts/' Folder| -| DONE! | Mobile Viewing of the Website| -| TO BE DONE! | Refactoring of the Code (Removing Garbage-Code) +**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 --- -## 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"**: - - Will have support for mobile devices - - Scrolling will be "different" (auto header scroll trough links) - - Styling will be responsive! +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 --- -## Closing Statements - -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. -Yeah fuck JavaScript, TypeScript is better. - - -- Thanks Rattatwinko ; 17.05.2025 - - +> **Happy Blogging!** 🎉 +> +> *"DEVELOPERS! DEVELOPERS! DEVELOPERS!"* - Steve Ballmer +> +> — Rattatwinko, 2025 Q3 \ No newline at end of file