https://github.com/timonrieger/blog-boiler-pro
Flask boilerplate for creating an advanced database-based blog.
https://github.com/timonrieger/blog-boiler-pro
blog boilerplate database flask template
Last synced: 4 months ago
JSON representation
Flask boilerplate for creating an advanced database-based blog.
- Host: GitHub
- URL: https://github.com/timonrieger/blog-boiler-pro
- Owner: timonrieger
- License: mit
- Created: 2025-01-08T18:41:14.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-14T10:18:04.000Z (about 1 year ago)
- Last Synced: 2025-07-12T12:14:24.036Z (12 months ago)
- Topics: blog, boilerplate, database, flask, template
- Language: Python
- Homepage:
- Size: 18.5 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Blog Boiler Pro
A lightweight Flask-based boilerplate for creating an advanced blog with database storage.
Home
Login
Register
Post Page
Comment View
Post Panel
Author Page
## Intention
This project is a advanced blog implementation, designed for users who prefer a more complete solution. If you don't require features like user management, an admin interface, or database storage, consider checking out [the lite version](https://github.com/timonrieger/blog-boiler-lite).
## Demo
I [extended and customised](https://github.com/timonrieger/blog) this template myself for [my personal blog](https://blog.timonrieger.de/). Check it out, to see it in action!
## Features
- **Create, Edit, Draft, Preview and Delete Blog Posts:** Easily manage blog content with intuitive CRUD operations with database storage.
- **Pagination:** View posts with pagination for better navigation and user experience.
- **User-Friendly Text Editor:** A simple and intuitive editor for creating and editing blog posts provided by CKEditor 4.
- **Responsive Design with Bootstrap:** The site automatically adjusts to various screen sizes and devices for seamless usability.
- **Collaboration Support:** Give admin access to co-authors to collaborate on the blog.
- **Secure, SEO Optimized, and Fast:** Optimized for performance and search engine visibility according to [Checkbot](https://checkbot.io/).
- **Customizable About Page:** Personalize an "About" page for each author to share their story or expertise.
- **User Management:** Basic functionality to manage users: registration, login, anonymous users, and admin management.
- **Admin Privileges:** Assign co-authors the admin role to write, edit, delete their blog posts and all comments. You remain the Super Admin.
- **Multi Language Support:** Use the language your are writing in for the whole application (Read on)
- **Commenting System:** Users can publish and edit comments on posts, with moderation capabilities for the comment author and admins.
- **Soft deletion with undo option**: Deleting posts and comments does not erase them entirely, but rather flag and hide them.
- **Filter by tag, author and year**: Posts can be filtered by tag, author and year to narrow down the results.
- **RSS Support**: Auto-generated RSS feed, which users can subscribe to with their RSS-Reader to receive new posts comfortably.
- **HTTP/Browser Caching Strategy**: Invalidates the browser cache for changed content, else uses the cached version.
## Limitations
- No extension or plugin system
- No analytics by default (which I regard as positive)
- No file upload
- No account settings for users, like confirmation email or password reset ([add an authentication microservice](https://github.com/timonrieger/auth-service))
## Setup
1. **Clone the repository**
```
git clone https://github.com/timonrieger/blog-boiler-pro.git
```
2. **Navigate to the project directory**
```
cd blog-boiler-pro
```
3. **Create a virtual environment**
```
python -m venv venv
```
4. **Activate the virtual environment**
- On Windows:
```
venv\Scripts\activate
```
- On macOS/Linux:
```
source venv/bin/activate
```
5. **Install the required dependencies**
```
pip install -r requirements.txt
```
6. Set the required **environment variables** in a `.env` at the root directory.
```
SECRET_KEY=yoursecretkey
DB_URI=postgresql://username:password@host:port/db
ANONYMOUS_ID=1 # register the first user with username "anonymous" or similar for letting users comment anonymously
SUPER_ID=2 # register yourself, set as admin in the database and define your ID in the `.env`
```
7. **Run the application**
```
python -m main
```
Now go to http://127.0.0.1:5000/ and register the first two users (anonymous and yourself) as mentioned in step 6
## Your First Blog Post
1. **Create a New Blog Post**
- Go to http://127.0.0.1:5000/new after logging in with your account. This will open the form to write a new blog post.
- Fill the form with your content.
2. **Add Images to Your Blog Post**
- Upload your image to the `static/uploads/` directory.
- To display the image in the blog post, use the following HTML code in your post content or add the URL in CKEditors image interface:
```
```
3. **Set Blog Image URL**
- For the field `Blog Image URL` field, use the path of the uploaded image, e.g., `/static/uploads/3.png`.
4. **Submit the form**
> **Warning**: Before submitting the form, copy the source HTML code to avoid data loss in case application fails. You can usually go back in the browser to load the filled form again, though.
## Configuration
1. **Add Images**
Add the images you want to use in the `static/uploads/` directory with your image files (I personally name the files with [autoincrementing numbers](https://github.com/timonrieger/blog/tree/main/static/uploads)).
2. **Modify Static Assets**
Feel free to modify the following directories and files:
- `static/assets/img/` (for images)
- `static/assets/favicon.ico` (for the site favicon)
3. **Modify SEO contents**
Replace the contents at the top of each file in the `templates/`
directory to reflect your content.
4. **Edit author pages**
Edit the contents in the author files in `templates/authors/`. Change the name of the file to the username you registered as well as the profile picture in `static/assets/img/`, e.g. John Doe > `john-doe.html` and `john-doe.jpg`
5. **Update the `src/config.py` configuration file**
- `LANGUAGE`: Your blog should be in a different language than English? start here
- `DISPLAY_READING_TIME`: Show the approximate reading time on each post (True/False).
- `DISPLAY_EDIT_DATE`: Show the edit date if you edited the post body (True/False).
- `DRAFT_ON_DEFAULT`: Sets the checkbox to publish as draft in the post form on default (True/False).
- `LEVEL_ADMINS`: Whether all admins have should have all right. Useful if you work together and trust each other. (True/False)
- `TIMEZONE_OFFSET`: Set the offset to UTC (e.g. for New York -5) (± number)
- `DATE_FORMAT`: The format for dates (used everywhere except comments) (valid datetime format).
=> [Datetime Format Guide](https://www.pythonmorsels.com/strptime/) and [Date Format Patterns](https://unicode.org/reports/tr35/tr35-dates.html#date-format-patterns)
- `CHECK_EMAIL`: Whether to check if the email is valid/delivarable (True/False)
- `IMAGES_FOLDER`: The path to your images folder (path).
- `POSTS_PER_PAGE`: Number of posts on the home route before displaying pagination buttons (integer).
- `NR_RELATED_POSTS`: Number of related (same tags) posts at the end of a post
- `COMMENT_RICH_EDITOR`:
- `True`: Uses a rich text editor (Ckeditor) for comments, making it easy for users to format content, but may increase the risk of misuse.
- `False`: Uses a plain text area. HTML is still allowed, but the user experience is simpler.
- `SHOW_COMMENT_TUTORIAL` :
Controls whether the `How to comment` tutorial link is shown.
- Links to: [Tutorial Image](/.github/demo/comments.png)
- `True`: Displays the tutorial link.
- `False`: Hides the tutorial link.
- `BLOG_NAME`: The name of your blog (string).
- `BLOG_TITLE`: The title that shows up on search machines for the home page (string).
- `BLOG_DESCRIPTION`: The description that shows up on search machines for the home page (string).
## Multi-Language Support
The blog currently supports **English** (`en`) and **German** (`de`).
When setting up your blog, you can define the default language for your application. The intent is not for users to switch between languages dynamically but to ensure that application texts align with the language you are writing in.
### Contribute a New Language
If you'd like to contribute a new language you're fluent in, feel free to submit a Pull Request (PR) containing the translated `message.po` file for that language. Your contribution is highly appreciated! Note that there are approximately **75 phrases/sentences** to translate, making it a manageable task.
### Using a Different Language Without Translating
If you'd rather use a different language without contributing translations, start by following the instructions in the section [Compile the Language](#compile-the-language).
### Translating a Language
If you'd like to help translate, follow these steps:
1. Navigate to the project root.
```bash
cd /path/to/project
### Get all languages available
```bash
find translations -mindepth 1 -maxdepth 1 -type d
```
### Get all strings for translation
Extracts all translateable strings from the `.html` and `.py` files into `message.pot`.
```bash
pybabel extract -F babel.cfg -k lazy_gettext -o translations/messages.pot .
```
### a) Initialize a language (ONLY ONCE)
```bash
pybabel init -i translations/messages.pot -d translations -l LANG_LOCAL
```
### b) Update a language
```bash
pybabel update -i translations/messages.pot -d translations
```
### Translate
We have to translate manually, but you can start out with [Deepl in VSCode](https://marketplace.visualstudio.com/items?itemName=soerenuhrbach.vscode-deepl). We use common not highly formal language.
Fill the `msgstr ""` in the `LANG_LOCAL/LC_MESSAGES/messages.po` with the translation. Check existing languages if you're lost.
`⌘F` and search for the term `fuzzy` and delete it ([docs](https://python-babel.github.io/flask-babel/#translating-applications)).
### Compile the language
Compiles all languages for usage.
```bash
pybabel compile -f -d translations
```
### Apply and reload
In `src/config.py` change `LANGUAGE` to the language locale you want, then run:
```bash
python -m main
```
## Roles
There are five types of users:
- Non logged in users: `read` access
- Anonymous user: as above + `write:comment`
- Logged in users: as above + `delete:own_comment`
- Admin user: as above + `write:post`, `edit:own_post`, `delete:own_post`
- Super admin (only one, YOU): full access (can delete, edit, write anything)
=> you can level all admins to the super admin role (see configuration section)
## Endpoints
- **Home**: `/` - View all blog posts.
- **Show Post**: `/` - View a single blog post. Add comment logic here as well.
- **New Post**: `/new` - Create a new blog post.
- **Edit Post**: `//edit` - Edit an existing blog post.
- **Delete Post**: `//delete` - Soft deletes a single blog post.
- **Restore Post**: `//restore` - Restores/Unhides a single blog post.
- **Delete Comment**: `//delete/comment/` - Soft deletes a single comment.
- **Restore Comment**: `//restore/comment/` - Restores/Unhides a single comment.
- **Show Author** - `/author/` - View an author's page.
- **Login**: `/login` - Login as a user or anonymously.
- **Register**: `/register` - Register a user.
- **Logout**: `/logout` - Logout a user.
- **RSS**: `/feed`, `/rss` and `/rss.xml` - Load blog feed users can subscribe to.
## Requirements
- Python 3.x
- The following Python packages (as listed in `requirements.txt`)
- A hosting service to deploy your blog to ([Vercel](https://vercel.com/), [Render](https://render.com/) etc.)
- A database ([Supabase](https://supabase.com/) is free)
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.