Improve documentation to enable social meta tags rendering

nephila · Jul 11, 2020 · 535a65d · 535a65d
1 parent c26de68
commit 535a65d
Show file tree

Hide file tree

Showing 6 changed files with 75 additions and 6 deletions.
diff --git a/changes/613.doc b/changes/613.doc
@@ -0,0 +1 @@
+Improve documentation to enable social meta tags rendering
diff --git a/djangocms_blog/templates/djangocms_blog/base.html b/djangocms_blog/templates/djangocms_blog/base.html
@@ -1,7 +1,21 @@
 {% extends CMS_TEMPLATE %}
 
 {% block meta %}
-    {%  if meta %}
+    {% comment %}
+    This is needed if you can't add ``{% include "meta/meta.html" %}`` in the django CMS template attached to the blog
+    page.
+    If you have something like the snippet below in the main template used by the django CMS page, you don't need
+    this block and you can safely remove it when customizing the blog templates
+
+    ...
+    <html>
+        <head>
+        <title>{% block title %}{% page_attribute 'title' %}{% endblock title %}</title>
+        {% include "meta/meta.html" %}
+        ...
+
+    {% endcomment %}
+    {% if meta %}
         {% include "meta/meta.html" %}
     {% endif %}
 {% endblock meta %}

diff --git a/docs/features/index.rst b/docs/features/index.rst
@@ -11,12 +11,13 @@ Features
    urlconf
    permalinks
    templates
+   meta
    shares
    media
    menu
    multisite
    related
    channels
    wizard
-   cmsplugin_filer
    extensions
+   cmsplugin_filer
diff --git a/docs/features/meta.rst b/docs/features/meta.rst
@@ -0,0 +1,53 @@
+.. _meta:
+
+###############################
+Setup social metatags rendering
+###############################
+
+djangocms-blog implements `django-meta <https://github.com/nephila/django-meta>`_ and it come ready to provide a
+fairly complete social meta tags set.
+
+Custom metatags are rendered on the blog post detail page only, while on the list page (which is a basically django CMS page)
+you can use `djangocms-page-meta <https://github.com/nephila/djangocms-page-meta/>`_ to render meta tags based on the django CMS
+page object.
+
+In order to enable its rendering you must follow two steps:
+
+* Enable ``django-meta`` settings in the project ``settings.py``
+
+  .. code-block:: python
+
+      META_SITE_PROTOCOL = 'https'  # set 'http' for non ssl enabled websites
+      META_USE_SITES = True
+      META_USE_OG_PROPERTIES=True
+      META_USE_TWITTER_PROPERTIES=True
+      META_USE_GOOGLEPLUS_PROPERTIES=True # django-meta 1.x+
+      META_USE_SCHEMAORG_PROPERTIES=True  # django-meta 2.x+
+
+
+* Include ``meta/meta.html`` in the ``head`` tag of the template used to render ``djangocms-blog``.
+
+  a. The recommended way is to include in your project base templates:
+
+     .. code-block:: html+django
+         :name: my_base.html
+
+         <html>
+         <head>
+            <title>{% block title %}{% page_attribute 'title' %}{% endblock title %}</title>
+            {% include "meta/meta.html" %}
+            ...
+
+  b. alternatively djangocms-blog base template provide a ``meta`` block you can place in your templates to only include ``meta.html``
+     for the blog posts:
+
+     .. code-block:: html+django
+         :name: base.html
+
+         <html>
+         <head>
+            <title>{% block title %}{% page_attribute 'title' %}{% endblock title %}</title>
+            {% block meta %}{% endblock meta %}
+            ...
+
+For complete social meta tags rendering, configure default properties (see ``BLOG_FB``, ``BLOG_TWITTER``, ``BLOG_GPLUS``/``BLOG_SCHEMAORG`` in :ref:`settings`) and apphook ones.
diff --git a/docs/installation.rst b/docs/installation.rst
@@ -75,14 +75,15 @@ suited for your deployment.
         'filer.thumbnail_processors.scale_and_crop_with_subject_location',
         'easy_thumbnails.processors.filters',
     )
-    META_SITE_PROTOCOL = 'http'
+    META_SITE_PROTOCOL = 'https'  # set 'http' for non ssl enabled websites
     META_USE_SITES = True
 
 * For meta tags support enable the needed types::
 
     META_USE_OG_PROPERTIES=True
     META_USE_TWITTER_PROPERTIES=True
-    META_USE_GOOGLEPLUS_PROPERTIES=True
+    META_USE_GOOGLEPLUS_PROPERTIES=True # django-meta 1.x+
+    META_USE_SCHEMAORG_PROPERTIES=True  # django-meta 2.x+
 
 * Configure parler according to your languages:
 
@@ -146,7 +147,6 @@ Please, refer to each application documentation on details.
 * django-cms: http://django-cms.readthedocs.io/en/release-3.4.x/how_to/install.html
 * django-filer: https://django-filer.readthedocs.io
 * django-meta: https://github.com/nephila/django-meta#installation
-* django-meta-mixin: https://github.com/nephila/django-meta-mixin#installation
 * django-parler: https://django-parler.readthedocs.io/en/latest/quickstart.html#configuration
 * django-taggit-autosuggest: https://bitbucket.org/fabian/django-taggit-autosuggest
 * aldryn-search: https://github.com/aldryn/aldryn-search#usage>

diff --git a/tests/test_utils/templates/blog.html b/tests/test_utils/templates/blog.html
@@ -3,9 +3,9 @@
 <html>
 <head>
     <title>{% block title %}{% page_attribute 'title' %}{% endblock title %}</title>
+    {% include "meta/meta.html" %}
     {% render_block "css" %}
     {% block canonical_url %}{% endblock canonical_url %}
-    {% include "meta/meta.html" %}
     <style type="text/css">
         .nav {
             padding-left: 0;