Puput Documentation

repository·master·Indexed 20 days ago

A Django-based blogging application using Wagtail CMS for content management. Puput provides SEO-friendly URLs, RSS feeds, and support for Disqus or Django comments. It features extensible BlogPage and EntryPage models via BlogAbstract and EntryAbstract, and includes importers for migrating data from WordPress, Zinnia, and Blogger.

Tokens: 5K
Snippets: 24
Records: 33
Agent score: 71%

What's inside Puput

Overview of Puput
master
Puput is a Django application designed for managing a blog. It leverages the Wagtail CMS as its content management system. It is inspired by WordPress and Zinnia and provides a simple, responsive HTML template by default.
Key features include:
- SEO friendly URLs
- Support for Disqus comments
- Organization by author, tags, categories, archives, and search terms
- RSS feeds and related entries
- Configurable sidebar widgets and default template colors
- Social sharing (Facebook, Twitter, LinkedIn)
- Markdown field support via wagtail-markdown
https://github.com/apsl/puput/blob/master/README.rst
Overview of Puput features
master
Puput is a Django application designed for blog management, built on top of the Wagtail CMS. It provides a feature-rich blogging experience inspired by WordPress and Zinnia.
Key features include:
- CMS Integration: Built with Wagtail CMS and Django.
- SEO & Navigation: SEO-friendly URLs, RSS feeds, and entries organized by author, tags, categories, archives, and search terms.
- Engagement: Support for Disqus comments and social sharing (Facebook, Twitter, and LinkedIn).
- UI/UX: Simple and responsive HTML templates by default, configurable sidebar widgets, and configurable default template colors.
- Content Discovery: Related entries, last entries, and popular entries.
- Extensibility: An extensible entry model for custom requirements.
https://github.com/apsl/puput/blob/master/docs/index.rst
Structure multi-blog sites in Puput
master
Puput follows a tree-based architecture inspired by Wagtail. You can host multiple independent blog instances within a single Puput installation by nesting them under different parent pages.
Hierarchy Rules:
- Blog pages can act as parents.
- Entry pages must be children of Blog pages.
- All Blog pages must have a Root page as their parent.
This allows for URL separation, such as:
- http://www.example.com/blog/
- http://www.example.com/tv/ (a separate videoblog instance)
https://github.com/apsl/puput/blob/master/docs/sites.rst
Install system prerequisites for importers
master
All Puput importers require the lxml Python package, which depends on libxml2 and libxslt system libraries. Install these dependencies based on your operating system:
Ubuntu:
```
sudo apt-get install libxml2-dev libxslt-dev
```
CentOS or Red Hat:
```
sudo yum install libxml2-devel libxml++-devel libxslt-devel
```
```
sudo apt-get install libxml2-dev libxslt-dev
```
https://github.com/apsl/puput/blob/master/docs/importers.rst
Import data from Blogger
master
To migrate a Blogger blog to Puput, follow these steps:
1. Install the importer package: pip install blogger2puput.
2. Add blogger2puput to your INSTALLED_APPS in settings.py.
3. Run the management command providing your Blogger Blog ID and API Key using the --blogger_blog_id and --blogger_api_key flags.
You can also optionally specify the blog's slug and title using --slug and --title flags.
```
python manage.py blogger2puput --blogger_blog_id=Your BlogID --blogger_api_key=Your APIKey --slug=blog --title="Puput blog"
```
https://github.com/apsl/puput/blob/master/docs/importers.rst
Register a custom Blog model extension
master
After defining your abstract model, you must tell Puput to use it instead of the default BlogPage. Register your model in your project's settings.py using the PUPUT_BLOG_MODEL setting. The value should be the full Python path to your abstract model.
```
PUPUT_BLOG_MODEL = 'app_name.models.MyBlogAbstract'
```
https://github.com/apsl/puput/blob/master/docs/extending_blog.rst
Install Puput as a standalone blog app
master
If you are starting a new Django project without Wagtail and want to add a blog, follow these steps:
1. Install dependencies: Run pip install puput.
2. Configure Apps: Append PUPUT_APPS to your INSTALLED_APPS in Django settings.
  Note: If you are manually listing apps, ensure wagtail, taggit, modelcluster, and puput are included to avoid collisions.
3. Middleware: Add wagtail.contrib.redirects.middleware.RedirectMiddleware to your MIDDLEWARE list.
4. Template Context: Add django.template.context_processors.request to your TEMPLATES context processors.
5. Site Settings: Set WAGTAIL_SITE_NAME and WAGTAILADMIN_BASE_URL.
6. Media Configuration: Configure MEDIA_ROOT and MEDIA_URL.
7. URLs: Include puput.urls at the bottom of your urlpatterns.
8. Development Media: If in DEBUG mode, configure urlpatterns to serve static and media files.
9. Initialize: Run migrations and the initial data loader.
Access the blog at /blog/ and the admin at /blog_admin/.
```
from puput import PUPUT_APPS

INSTALLED_APPS += PUPUT_APPS

# Required Settings
WAGTAIL_SITE_NAME = 'Puput blog'
WAGTAILADMIN_BASE_URL = 'http://localhost:8000/'

# Media Settings
import os
MEDIA_ROOT = os.path.join(PROJECT_ROOT, 'media')
MEDIA_URL = '/media/'

# URLs (must be at the bottom)
urlpatterns = [
    ...
    path(r'', include('puput.urls')),
]
```
https://github.com/apsl/puput/blob/master/docs/setup.rst
Configure migrations for EntryPage extensions
master
When extending the EntryPage model (multi-table inheritance), running makemigrations might attempt to write migrations into the Puput package directory. To prevent this, use the MIGRATION_MODULES setting to redirect Puput's migrations to a folder within your own project.
Recommended Workflow: To avoid conflicts, run makemigrations puput before defining your PUPUT_ENTRY_MODEL in settings.py.
```
# settings.py
MIGRATION_MODULES = {'puput': 'youproject.puput_migrations'}
```
https://github.com/apsl/puput/blob/master/docs/extending_entry.rst
Use Disqus as a comment provider
master
To use Disqus, set PUPUT_COMMENTS_PROVIDER to 'puput.comments.DisqusCommentsProvider'.
To display comments, you must provide your Disqus shortname. If you also want to retrieve the number of comments for each entry, you must provide the Disqus api secret.
If you provide the API secret, you must install the tapioca-disqus package.
```
PUPUT_COMMENTS_PROVIDER = 'puput.comments.DisqusCommentsProvider'
```
https://github.com/apsl/puput/blob/master/docs/comments.rst
Configure a single blog site at the domain root
master
To make a single blog the primary content of your domain (e.g., serving http://www.myblog.com instead of http://www.myblog.com/blog/), you must modify the site configuration.
1. Navigate to the Sites section in the Puput admin interface (typically found under the site configuration settings).
2. Locate your primary site entry.
3. Change the root page of the site to your desired Blog page instead of the default root page.
https://github.com/apsl/puput/blob/master/docs/sites.rst
Run Puput using Docker
master
For detailed instructions on running Puput in a Docker container, visit the official docker-puput repository: https://github.com/APSL/docker-puput/
https://github.com/apsl/puput/blob/master/docs/setup.rst
Import data from WordPress
master
To migrate a WordPress blog to Puput, follow these steps:
1. Install the importer package: pip install wordpress-to-puput.
2. Add wordpress2puput to your INSTALLED_APPS in settings.py.
3. Run the management command providing the path to your WordPress XML export file: python manage.py wp2puput path_to_wordpress_export.xml.
You can optionally specify the blog's slug and title using --slug and --title flags.
```
python manage.py wp2puput path_to_wordpress_export.xml --slug=blog --title="Puput blog"
```
https://github.com/apsl/puput/blob/master/docs/importers.rst