Interim update

README.md

@@ -1,23 +1,28 @@
-# Zendesk support integration
-This is a work in progress and is currently not ready for use.
+# Nabu Casa Support
+This repo provides the theme, content and assets for Zendesk support for Nabu Casa. It allows anyone to contribute to the support documentation in one place and have it automatically deployed to Zendesk.
 
-This repo is made to sync source content to Zendesk using their API. It will provide documentation and support articles instead of using the Zendesk editor.
+## How does it work?
+There are a few moving parts to this repository:
 
-The ideal goals for this repo are as follows:
-
-- To keep all support documentation open source
-- To standardise the way support documentation is written
-- To maintain the theme within Zendesk
+- Zendesk - Uses this repo as the theme for the Nabu Casa support website
+- GitHub Actions - Responsible for deploying content to Zendesk via the REST API and uploading static assets to Cloudflare R2
 
 # Folder structure
-The folder structure of this repo is purely for organisation and to make it easier to understand but also mimics the structure of articles in Zendesk.
+### Zendesk theme
+The Zendesk theme is stored in the root of the repository as per the [requirements of Zendesk](https://support.zendesk.com/hc/en-us/articles/4408832476698-Setting-up-the-GitHub-integration-with-your-Guide-theme#topic_i3v_kyk_chb).
+
+### Content
+This is a custom implementation of using version control to manage content for Zendesk. The goal is to use DITA as the publishing arhitecture with the [Markdown flavour](https://www.dita-ot.org/dev/reference/markdown/markdown-dita-syntax).
+
+Upon a push to the `main` branch, the GitHub Action will validate the DITA syntax, convert the Markdown to HTML and upload the content to Zendesk via the REST API.
+
+Since we want to manage all content in Zendesk (including categories and sections), there is a specific structure to the `/content` folder.
 
-All `.md` files within the `content/` folder will be treated as something that relates to a Zendesk object. The folder structure is as follows:
+All `.md` files within the `content/` folder will be treated as something that relates to a Zendesk object. Metadata is defined using frontmatter syntax. The folder structure under `/content` is as follows:
 
-- `_assets/` - Assets (such as images) for articles to use directly (not uploaded to Zendesk)
-- `content/` - Content that will be sent to Zendesk. 
-    - `{category}/` - Used to group sections together. Purely for organisation in the repo
-        - `_category.md` - Metadata that describes the category for Zendesk
-        - `{section}/` - Used to group articles together. Purely for organisation in the repo
-            - `_section.md` - Metadata that describes the section for Zendesk
-            - `{article}.md` - The article that will be sent to Zendesk
+
+- `{category}/` - Used to group sections together. Purely for organisation in the repo
+    - `_category.md` - (required) Metadata that describes the category for Zendesk
+    - `{section}/` - Used to group articles together. Purely for organisation in the repo
+        - `_section.md` - (required) Metadata that describes the section for Zendesk
+        - `{article}.md` - The article that will be sent to Zendesk. It also contains metadata for the article

content/deploy.js

@@ -3,14 +3,12 @@ import Showdown from 'showdown';
 
 const showdown = new Showdown.Converter();
 
-// find src="/assets/xyz" and replace with src="{{ asset 'xyz' }}"
+// find src="/static/img/xyz" and replace with src="{{ asset 'xyz' }}"
 showdown.setFlavor('github');
 showdown.addExtension({
     type: 'output',
     filter: function (text, converter, options) {
-        return text.replace(/src="\/assets\/(.*?)"/g, (match, p1) => {
-            return `src="\"{{ asset '${p1}' }}\""`;
-       })
+        return text.replace(/src="\/static\/img\/(.*?)"/g, 'alt="{{asset \'$1\'}}"');
     }
 });
 
@@ -75,13 +73,6 @@ function parseFile(raw) {
     };
 }
 
-function fixAssetEscape(content) {
-    // replace src="{{%20asset%20'green-connect-ethernet.webp'%20}}" with src="{{ asset 'green-connect-ethernet.webp' }}"
-    return content.replace(/src="{{%20asset%20'(.*?)'%20}}"/g, (match, p1) => {
-        return `src="{{ asset '${p1}' }}"`;
-    });
-
-}
 function updateArticle(article, section, category) {
     if(!article || !section || !category) return;
 

content/green/getting-started/prerequisites.md

@@ -5,7 +5,7 @@ name: Prerequisites
 
 There are a few things you require to start using your Home Assistant Green, some of which comes in the box.
 
-![Home Assistant Green with Power Supply](/assets/images/green-box-contents.webp)
+![Home Assistant Green with Power Supply](/static/img/green-box-contents.webp)
 
 - The Home Assistant Green device itself
 - An Ethernet connection to your local network with internet access (cable included)

content/green/getting-started/setting-up-the-device.md

@@ -2,42 +2,43 @@
 article_id: 24737667232413
 name: Setting up the device
 ---
-Whilst the Home Assistant Green is plug-and-play, it's important to follow these steps to ensure that the device boots up correctly.
 
+Whilst the Home Assistant Green is plug-and-play, it's important to follow these steps to ensure that the device boots up correctly.
 
 **Step 1 - Ethernet connection**
 
-![](/assets/images/green-connect-ethernet.webp)
+![](/static/img/green-connect-ethernet.webp)
+{{ asset "green-connect-ethernet.webp" }}
 
 1.  Plug in your Ethernet cable and make sure it is locked into place.
 2.  Connect the other end of the Ethernet cable to your router or switch.
 
+Result Description Name Number
+non-
 
 **Step 2 - Turn it on!**
 
-![](/assets/images/green-connect-power.webp)
+![](/static/img/green-connect-power.webp)
 
 Connect the power to the electrical outlet and then to the Home Assistant Green
 
-
 **Step 3 - Check the status light**
 
-![](/assets/images/green-heartbeat.webp)
+![](/static/img/green-heartbeat.webp)
 
 Wait for a few minutes until the yellow light starts blinking in a heartbeat pattern.
 
 **Step 4 - Get started with Home Assistant**
 
 Initial start-up may take a while, depending on your internet connection. Whilst you wait, proceed with the following:
 
--   Install the app - To access Home Assistant from your mobile device, use the QR code to locate the app in the app store.
--   Select your Home Assistant server
-    -   Mobile - Confirm the IP address detected by the app. For example  [http://192.168.1.196:8123](http://192.168.1.196:8123/)
-    -   Desktop: Visit http://homeassistant.local:8123 to access the Home Assistant user interface.
-
+- Install the app - To access Home Assistant from your mobile device, use the QR code to locate the app in the app store.
+- Select your Home Assistant server
+  - Mobile - Confirm the IP address detected by the app. For example [http://192.168.1.196:8123](http://192.168.1.196:8123/)
+  - Desktop: Visit http://homeassistant.local:8123 to access the Home Assistant user interface.
 
-![](/assets/images/home-assistant-app-qr-codes.webp)
+![](/static/img/home-assistant-app-qr-codes.webp)
 
 The Home Assistant user interface will guide you though the initial onboarding.
 
-For further information, refer to the instructions provided under  [https://www.home-assistant.io/getting-started/onboarding/](https://www.home-assistant.io/getting-started/onboarding/).
+For further information, refer to the instructions provided under [https://www.home-assistant.io/getting-started/onboarding/](https://www.home-assistant.io/getting-started/onboarding/).