From 13b1db8945294f5828b175d4df406d6a7c232c31 Mon Sep 17 00:00:00 2001
From: Luca <adobe@gituser.de>
Date: Thu, 14 Mar 2024 17:01:04 +0100
Subject: [PATCH] add docs for creating new categories

---
 .hlxignore                           |  2 +
 cigaradvisor/docs/create-category.md | 64 ++++++++++++++++++++++++++++
 2 files changed, 66 insertions(+)
 create mode 100644 cigaradvisor/docs/create-category.md

diff --git a/.hlxignore b/.hlxignore
index c5059166..a49a11ef 100644
--- a/.hlxignore
+++ b/.hlxignore
@@ -5,3 +5,5 @@ LICENSE
 package.json
 package-lock.json
 test/*
+
+cigaradvisor/docs/*
diff --git a/cigaradvisor/docs/create-category.md b/cigaradvisor/docs/create-category.md
new file mode 100644
index 00000000..f32de3b4
--- /dev/null
+++ b/cigaradvisor/docs/create-category.md
@@ -0,0 +1,64 @@
+# Creating a new category
+
+## Step 1: Create index configuration
+
+The configurations for the indices are located in [helix-query.yaml](../../helix-query.yaml).
+In here you just need to copy one of the existing category indices and replace all name occurrences:
+
+```diff
+@@ -259,6 +259,12 @@
+     exclude: *excludes
+     target: /cigaradvisor/index/article-index-cuban-cigar-guides.json
+     properties: *articles_properties
++  <new-category>:
++    include:
++      - /cigaradvisor/<new-category>/*
++    exclude: *excludes
++    target: /cigaradvisor/index/article-index-cuban-cigar-guides.json
++    properties: *articles_properties
+   uncategorized:
+     include:
+       - /cigaradvisor/uncategorized/*
+```
+
+The `pages`, `categories`, `authors` and `article` indices also contain a list of all the category paths in either their `includes` or `excludes`. Add the path of the new category (matching the structure of the other categories) to all of these lists.
+
+## Step 2: Create sitemap configuration
+
+The configurations for the indices are located in [helix-sitemap.yaml](../../helix-sitemap.yaml).
+In here you just need to copy one of the existing category indices and replace all name occurrences:
+
+```diff
+@@ -59,6 +59,11 @@
+     source: /cigaradvisor/index/article-index-cuban-cigar-guides.json
+     destination: /cigaradvisor/article-sitemap-cuban-cigar-guides.xml
+     lastmod: YYYY-MM-DD hh:mm:ss
++  <new-category>:
++    origin: https://www.famous-smoke.com
++    source: /cigaradvisor/index/article-index-<new-category>.json
++    destination: /cigaradvisor/article-sitemap-<new-category>.xml
++    lastmod: YYYY-MM-DD hh:mm:ss
+   uncategorized:
+     origin: https://www.famous-smoke.com
+     source: /cigaradvisor/index/article-index-uncategorized.json
+
+```
+
+## Step 3: Apply the configuration changes
+
+After merging the configuration / code changes to the `main` branch, the code-pipeline will apply your changes and register the new index and sitemap.
+
+## Step 4: Create sharepoint files
+
+Within Sharepoint you need to create a new directory with the same name as the category itself in the [cigaradvisor directory](https://famoussmokeshop.sharepoint.com/:f:/r/sites/AEM/webroot/www/cigaradvisor/cigaradvisor?csf=1&web=1&e=itmkNa).
+
+In the same parent folder you also need to create a new file for the category page. The easiest way to do so is duplicating one of the existing category pages and modifying the name and content to fit the new category. Furthermore, remember to also preview and publish this file.
+
+## Step 5: Publish your blogposts
+
+Now you should be all set to create and publish new pages in your previously created category directory.
+
+After publishing, they should appear in the corresponding index and sitemap (it may take a moment to generate these):
+
+- https://main--famous-smoke-cigaradvisor--hlxsites.hlx.page/cigaradvisor/index/article-index-<new-category>.json
+- https://main--famous-smoke-cigaradvisor--hlxsites.hlx.page/cigaradvisor/article-sitemap-<new-category>.xml