Django SDK Guide

Add an EarlySEO blog to your Django project with the earlyseo-blog Python package. Full setup with views, URLs, templates, and template tags.

Quick Start with CLI

The fastest way to add EarlySEO to your Django project:

pip install "earlyseo-blog[django]"
earlyseo-blog

The CLI will:

Detect your Django project
Ask for your Site ID (from Dashboard → Integrations → SDK)
Add earlyseo_blog.django to your INSTALLED_APPS
Generate starter templates and a .env file

Prefer manual setup? Follow the steps below.

Prerequisites

Python ≥ 3.9
Django ≥ 3.2
SDK integration enabled in EarlySEO (Dashboard → Integrations → SDK)
Site ID from the SDK integration card
At least one published article

Installation

pip install "earlyseo-blog[django]"

This installs the core package plus Django-specific extras (views, template tags, URL config).

Configuration

1. Add to INSTALLED_APPS

# settings.py
INSTALLED_APPS = [
    # …
    "earlyseo_blog.django",
]

2. Set your Site ID

# settings.py
EARLYSEO_SITE_ID = "your-site-id"

Or use an environment variable:

import os
EARLYSEO_SITE_ID = os.environ.get("EARLYSEO_SITE_ID", "")

URL Configuration

Include the EarlySEO URLs in your project's URL config:

# urls.py
from django.urls import include, path

urlpatterns = [
    # your other routes…
    path("blog/", include("earlyseo_blog.django.urls")),
]

This registers two routes:

URL Pattern	Name	Description
`/blog/`	`earlyseo_blog:blog_list`	Paginated article list (`?page=N`)
`/blog/<slug>/`	`earlyseo_blog:blog_detail`	Single article view

You can change the prefix to any path:

path("articles/", include("earlyseo_blog.django.urls")),

Built-in Templates

The package ships with built-in HTML templates that render a clean blog layout out of the box. No template files are required to get started.

Custom Templates

To customize the look of your blog, override the built-in templates by creating your own in your project's templates/ directory.

Blog list template

Create templates/earlyseo/blog_list.html:

{% raw %}
{% extends "base.html" %}
{% load earlyseo %}

{% block extra_head %}
  {% earlyseo_styles %}
{% endblock %}

{% block content %}
  <h1>Blog</h1>

  {% for article in articles %}
    <article>
      {% if article.featured_image_url %}
        <img src="{{ article.featured_image_url }}" alt="{{ article.title }}" />
      {% endif %}
      <h2>
        <a href="{% url 'earlyseo_blog:blog_detail' slug=article.slug %}">
          {{ article.title }}
        </a>
      </h2>
      <p>{{ article.meta_description }}</p>
    </article>
  {% endfor %}

  <!-- Pagination -->
  <nav>
    {% if current_page > 1 %}
      <a href="?page={{ current_page|add:'-1' }}">← Previous</a>
    {% endif %}
    <span>Page {{ current_page }} of {{ total_pages }}</span>
    {% if current_page < total_pages %}
      <a href="?page={{ current_page|add:'1' }}">Next →</a>
    {% endif %}
  </nav>
{% endblock %}
{% endraw %}

Context variables available:

Variable	Type	Description
`articles`	`list`	List of `ArticleListItem` objects
`current_page`	`int`	Current page number
`total_pages`	`int`	Total number of pages
`total_articles`	`int`	Total article count
`article_css`	`str`	Article-specific CSS
`blog_css`	`str`	Blog layout CSS

Blog detail template

Create templates/earlyseo/blog_detail.html:

{% raw %}
{% extends "base.html" %}
{% load earlyseo %}

{% block title %}{{ article.title }}{% endblock %}

{% block extra_head %}
  {% earlyseo_styles %}
  <meta name="description" content="{{ article.meta_description }}" />
{% endblock %}

{% block content %}
  {% earlyseo_article article %}
{% endblock %}
{% endraw %}

Context variables available:

Variable	Type	Description
`article`	`Article`	Full article object
`content_html`	`str`	Rendered HTML of the article body
`article_css`	`str`	Article-specific CSS
`blog_css`	`str`	Blog layout CSS

Template Tags

Load the EarlySEO template tags with {% raw %}{% load earlyseo %}{% endraw %}.

Tag	Description
`{% raw %}{% earlyseo_styles %}{% endraw %}`	Outputs a `<style>` block with article + blog CSS
`{% raw %}{% earlyseo_article_css %}{% endraw %}`	Outputs article CSS only
`{% raw %}{% earlyseo_article article %}{% endraw %}`	Renders full article HTML (header, featured image, body)

Using the Client Directly

For advanced use cases (APIs, management commands, etc.), use the client directly:

from earlyseo_blog import EarlySeoClient
from django.conf import settings

client = EarlySeoClient(site_id=settings.EARLYSEO_SITE_ID)

# In a view
def api_articles(request):
    page = client.get_list_page(1)
    data = [{"title": a.title, "slug": a.slug} for a in page.articles]
    return JsonResponse({"articles": data})

How Publishing Works

Write and publish an article in the EarlySEO dashboard
EarlySEO delivers your articles via a high-performance API
Your Django app fetches articles at request time via the earlyseo-blog package
Articles include SEO metadata automatically