Merge pull request #65 from Prisjakt/feat/restructure-docs

feat: Restructure docs

Author: andrejohansson

.idea/feed-specification.iml

@@ -1,4 +1,4 @@
 {
-  "label": "Advanced",
-  "position": 9
+  "label": "Advanced Topics",
+  "position": 8
 }

docs/advanced/_category_.json

@@ -1,6 +1,6 @@
-# Escaping data in CSV
+# Escaping Data
 
-If you need to use commas `,` within the value of your offers (for example in a title or a description) then we expect the csv cell to be enclosed in quotes `"` according to [RFC4180](https://datatracker.ietf.org/doc/html/rfc4180.html#section-2). For more information about our CSV support see our [CSV file format article](/types-of-feeds/pull/file-formats/csv.md).
+If you need to use commas `,` within the value of your offers (for example in a title or a description) then we expect the csv cell to be enclosed in quotes `"` according to [RFC4180](https://datatracker.ietf.org/doc/html/rfc4180.html#section-2). For more information about our CSV support see our [CSV file format article](/advanced/csv/index.md).
 
 > Fields containing line breaks (CRLF), double quotes, and commas should be enclosed in double-quotes.
 

docs/advanced/escaping/_category_.json renamed to docs/advanced/csv/_category_.json

@@ -1,20 +1,20 @@
 ---
-sidebar_position: 2
+sidebar_position: 1
 ---
 
 # CSV
 
 :::caution Recommendation
 
-While CSV is lightweight and easy to use, [XML](./xml.md) is more well defined and have better support for handling complex data encodings and strctures. We recommend using XML over CSV.
+While CSV is lightweight and easy to use, [XML](/advanced/xml/index.md) is more well defined and have better support for handling complex data encodings and strctures. We recommend using XML over CSV.
 
 :::
 
 [CSV](https://en.wikipedia.org/wiki/Comma-separated_values) stands for **c**omma **s**eparated **v**alues. It is a simple format very similar to having data organized in a spreadsheet. The CSV format is not fully standarized even if a proposed [RFC4180](https://datatracker.ietf.org/doc/html/rfc4180.html) exists and different software often interprets the structures differently.
 
 ## Format
 
-We expect the following structure (following  [RFC4180](https://datatracker.ietf.org/doc/html/rfc4180.html)) on CSV files, for a full example please see the [CSV tab on our full example](/examples/offer/all.mdx)
+We expect the following structure (following  [RFC4180](https://datatracker.ietf.org/doc/html/rfc4180.html)) on CSV files, for a full example please see the [CSV tab on our full example](/feeds/offer/formats/prisjakt_xml/index.md#full)
 
 - First row is a header row
 
@@ -42,7 +42,7 @@ We expect the following structure (following  [RFC4180](https://datatracker.ietf
 
 ## Escaping
 
-Escaping values in CSV can be tricky, see [our section about escaping](/advanced/escaping/escape-csv.md) for more details
+Escaping values in CSV can be tricky, see [our section about escaping](/advanced/csv/escaping-data.md) for more details
 
 ## Encoding sub-attributes and lists in CSV files
 While the XML format is well suited for sub-attributes (child elements) and lists (repeated elements), the CSV format is not so. 

docs/advanced/escaping/escape-csv.md renamed to docs/advanced/csv/escaping-data.md

@@ -1,3 +1,6 @@
+---
+sidebar_position: 1
+---
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 

docs/types-of-feeds/pull/file-formats/csv.md renamed to docs/advanced/csv/index.md

@@ -1,8 +1,11 @@
+---
+sidebar_position: 2
+---
 # Url Encoding
 
 [![What Is An Url?](@site/docs/assets/url.png)](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/What_is_a_URL)
 
-URLs are complex datatypes that carry a lot of information and can be a bit hard to handle sometimes. In this article we will try to explain how to deal with some tricky but not uncommon cases. All fields that are of type URL such as the [link](/fields/offer/link) field have both [valid examples](/fields/offer/link#example-values) and [invalid examples](/fields/offer/link#error-codes) of URLs in their respective sections.
+URLs are complex datatypes that carry a lot of information and can be a bit hard to handle sometimes. In this article we will try to explain how to deal with some tricky but not uncommon cases. All fields that are of type URL such as the [link](/feeds/offer/fields/link) field have both [valid examples](/feeds/offer/fields/link#example-values) and [invalid examples](/feeds/offer/fields/link#error-codes) of URLs in their respective sections.
 
 The image above is borrowed from Mozilla MDN[^1].
 

docs/advanced/encoding/index.md

@@ -1,3 +1,4 @@
 {
+  "label": "XML",
   "position": 2
 }

docs/advanced/escaping/index.md

@@ -1,6 +1,6 @@
 # CDATA in XML Files
 
-Since XML is a tag based language: `<tag>content</tag>` some characters like brackets (`<` or `>`) are reserved for the XML markup itself. If your data contains these characters it may cause a parser to become confused. We recommend that you embed **all fields that contain string values** in [CDATA](/advanced/encoding/cdata) tags in order to avoid the risk of your content causing troubles for our parser.
+Since XML is a tag based language: `<tag>content</tag>` some characters like brackets (`<` or `>`) are reserved for the XML markup itself. If your data contains these characters it may cause a parser to become confused. We recommend that you embed **all fields that contain string values** in [CDATA](/advanced/xml/cdata.md) tags in order to avoid the risk of your content causing troubles for our parser.
 
 ```xml
 <g:field><![CDATA[your complex string with special xml markup characters]]></g:field>

docs/advanced/encoding/file-encoding.md renamed to docs/advanced/file-encoding.md

@@ -0,0 +1,56 @@
+---
+sidebar_position: 1
+---
+
+```mdx-code-block
+import DocCardList from '@theme/DocCardList';
+
+<DocCardList />
+```
+
+
+# XML
+
+## Overview
+
+[XML](https://en.wikipedia.org/wiki/XML) stands for e**X**tensinble **M**arkup **L**anguage. It is very similar to HTML except it doesn't have any predefined tags. It's a meta language that allows you to define your own markup language which then can be used to store and share data in a structured manner.
+
+## Namespaces
+A Prisjakt offer feed should use two namespaces, the `g` namespace which most fields belong to that are defined by the Google Product Specification and then the `pj` namespace which contains some [additional Prisjakt specific fields](/feeds/offer/formats/prisjakt_xml/#prisjakt-specific-fields) defined by us.
+
+Offers: https://schema.prisjakt.nu/ns/1.0
+
+```xml
+<rss xmlns:pj="https://schema.prisjakt.nu/ns/1.0" xmlns:g="http://base.google.com/ns/1.0" version="3.0">
+```
+
+Promotions: https://schema.prisjakt.nu/ns/promotions-1.0
+
+```xml
+<rss xmlns:pj="https://schema.prisjakt.nu/ns/promotions-1.0" xmlns:g="http://base.google.com/ns/1.0" version="3.0">
+```
+
+### Namespace Priority When Parsed
+
+If multiple fields with the same name but different namespaces exist, the field will be parsed with the following priority:
+
+1. `pj:` first eg. `<pj:some_field>Some pj field</pj:some_field>`
+1. `g:` second eg. `<g:some_field>Gome g field</g:some_field>`
+1. **no namespace** third eg. `<some_field>Some field</some_field>`
+1. **other/unknown** in undefined order eg. `<xyz:some_field>Some xyz field</xyz:some_field>`
+
+## Recommendations
+
+### Use UTF-8
+
+All XML feeds should start with the following header and the files should be properly [UTF-8 encoded](/advanced/file-encoding.md).
+
+Do not use [control characters](https://en.wikipedia.org/wiki/Control_character) in feed file. We support some of them trying to follow [XML spec](https://en.wikipedia.org/wiki/Valid_characters_in_XML) but not guarantee to fully support it.
+
+```
+<?xml version='1.0' encoding='UTF-8'?>
+```
+
+### Use CDATA
+
+You should lower the risk of your data causing xml parsers to fail because of invalid data by encoding your data correctly. Take a look on our [CDATA](/advanced/xml/cdata.md) article to achieve this.

docs/advanced/encoding/url-encode.md renamed to docs/advanced/url-encode.md

@@ -1,6 +1,6 @@
 # Special Characters in XML
 
-It is possible to escape special characters in [XML](/types-of-feeds/pull/file-formats/xml.md) (see [this answer](https://stackoverflow.com/a/1091953) and [this answer](https://stackoverflow.com/a/46637835)) using number notations such as this example:
+It is possible to escape special characters in [XML](/advanced/xml/index.md) (see [this answer](https://stackoverflow.com/a/1091953) and [this answer](https://stackoverflow.com/a/46637835)) using number notations such as this example:
 
 
 ```
@@ -19,6 +19,6 @@ In order to test conversion and encoding you can use one of the many available o
 Joe's Café & Bar ♫
 ```
 
-But in the case of product feeds, **you should never need to do this** as long as your XML file is [UTF-8 encoded](./file-encoding.md) and that **all fields containing strings** are [wrapped in CDATA tags](./cdata.md). 
+But in the case of product feeds, **you should never need to do this** as long as your XML file is [UTF-8 encoded](/advanced/file-encoding.md) and that **all fields containing strings** are [wrapped in CDATA tags](./cdata.md). 
 
-Please note that for URLs we are more strict and require them to be [url encoded](./url-encode.md) properly according to RFC specification.
+Please note that for URLs we are more strict and require them to be [url encoded](/advanced/url-encode.md) properly according to RFC specification.

docs/advanced/encoding/_category_.json renamed to docs/advanced/xml/_category_.json

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 13
+sidebar_position: 10
 ---
 
 # FAQ

docs/advanced/encoding/cdata.md renamed to docs/advanced/xml/cdata.md

@@ -0,0 +1,4 @@
+{
+  "label": "Feeds",
+  "position": 3
+}

docs/advanced/xml/index.md

@@ -0,0 +1,28 @@
+# Feeds
+
+```mdx-code-block
+import DocCardList from '@theme/DocCardList';
+
+<DocCardList />
+```
+
+We support feeds for different types of entities that can be used to integrate with us. 
+
+- **Offer feed** is the most common feed type, compatible with Google Merchant Feed and is the way shops provide us with prices and stock status.
+- **Promotion feed** is a way for shops to automate promotion campains through us. Visible at [the promotions page](https://prisjakt.nu/kampanjer).
+- **Product feed** is intended for manufacturers who wants to provide us with detailed product information of the products they create.
+
+The flow of the feeds is a simple polling mechanism where you provide us with a URL to your feed and we will poll it according to your SLA.
+
+```mermaid
+%%{init: {'theme':'neutral'}}%%
+sequenceDiagram
+    participant A as Prisjakt Agent
+    participant F as Your Web Server
+
+    loop Periodically according to your SLA
+        A->>F: Requests Feed: <Your Feed Url>
+        F->>A: Responds With Feed
+        A->>A: Ingests Feed Data
+    end
+```

docs/advanced/encoding/xml-escaping.md renamed to docs/advanced/xml/xml-escaping.md

@@ -1,4 +1,4 @@
 {
   "label": "Offer",
-  "position": 1
-}
+  "position": 3
+}

docs/examples/_category_.json

@@ -1,4 +1,4 @@
 {
   "label": "Fields",
-  "position": 4
+  "position": 3
 }