From 3141a82ffe40165ae511c1757c1c4fec8120b1e7 Mon Sep 17 00:00:00 2001
From: iUnknwn <iUnknwn@users.noreply.github.com>
Date: Tue, 21 Sep 2021 17:45:20 -0700
Subject: [PATCH] Update docs with example on injecting articles

Updated the plugin documentation to add a recipe for adding articles
programatically when pelican is running.
---
 RELEASE.md       |  3 +++
 docs/plugins.rst | 37 +++++++++++++++++++++++++++++++++++++
 2 files changed, 40 insertions(+)
 create mode 100644 RELEASE.md

diff --git a/RELEASE.md b/RELEASE.md
new file mode 100644
index 00000000..9ca1dc84
--- /dev/null
+++ b/RELEASE.md
@@ -0,0 +1,3 @@
+Release type: minor
+
+Add additional documention on how to add new articles programatically.
\ No newline at end of file
diff --git a/docs/plugins.rst b/docs/plugins.rst
index 8e24b0af..7103e44d 100644
--- a/docs/plugins.rst
+++ b/docs/plugins.rst
@@ -301,6 +301,43 @@ Here is a basic example of how to set up your own writer::
         signals.get_writer.connect(add_writer)
 
 
+Modifying Generators to Inject Content
+---------------------------------------
+
+You can programatically inject articles or pages using plugins. This can be 
+useful if you plan to fetch articles from an API, for example. 
+
+Here is a very simple example of how we can build a plugin that injects
+custom articles, using the article `article_generator_pretaxonomy` signal::
+
+    from pelican import signals
+    from pelican.contents import Article
+    from pelican.readers import BaseReader
+    import datetime
+
+    def addArticle(articleGenerator):
+        settings = articleGenerator.settings
+
+        # Author, category, and tags are objects, not strings, so they need to
+        # be handled using BaseReader's process_metadata.
+        baseReader = BaseReader(settings) 
+
+        content = "I am the body of an injected article!"
+
+        newArticle = Article(content, {
+            "title": "Injected Article!",
+            "date": datetime.datetime.now(),
+            "category": baseReader.process_metadata('category', 'fromAPI'),
+            "tags": baseReader.process_metadata("tags", 'tagA, tagB')
+        })
+
+        articleGenerator.articles.insert(0, newArticle)
+
+    def register():
+        signals.article_generator_pretaxonomy.connect(addArticle)
+
+
+
 .. _Pip: https://pip.pypa.io/
 .. _pelican-plugins bug #314: https://github.com/getpelican/pelican-plugins/issues/314
 .. _Blinker: https://pythonhosted.org/blinker/