Cards docs

.gitignore

@@ -21,3 +21,5 @@ pnpm-debug.log*
 
 # macOS-specific files
 .DS_Store
+
+!src/content/docs/cards/tags/

astro.config.mjs

@@ -51,6 +51,53 @@ export default defineConfig({
               },
             ],
           },
+          {
+            label: "Cards",
+            collapsed: false,
+            items: [
+              {
+                label: "Introduction to Cards",
+                link: "/cards/cards-overview/",
+              },
+              {
+                label: "Cards",
+                collapsed: false,
+                items: [
+                  {label: 'Creating Cards', link: '/cards/cards/creating-cards/'},
+                  {label: 'Parent-child Cards', link: '/cards/cards/parent-child-cards/'},     
+                  {label: 'View, sort and filter Cards', link: '/cards/cards/view-sort-filter-cards/'},     
+                ]
+              },
+              {
+                label: "Types",
+                collapsed: false,
+                items: [
+                  {label: 'What are Types?', link: '/cards/types/types-overview/'},
+                  {label: 'Creating Types', link: '/cards/types/creating-types/'},
+                  {label: 'File Types', link: '/cards/types/file-types/'},                ]
+              },
+              {
+                label: "Tags",
+                collapsed: false,
+                items: [
+                  {label: 'What are Tags?', link: '/cards/tags/tags-overview/'},
+                  {label: 'Creating Tags', link: '/cards/tags/creating-tags/'},
+                  {label: 'Applying Tags to Cards', link: '/cards/tags/applying-tags/'},
+                ]
+              },
+              {
+                label: "Relations",
+                collapsed: false,
+                items: [
+                  {label: 'What are Relations?', link: '/cards/relations/relations-overview/'},
+                  {label: 'Defining Relations', link: '/cards/relations/defining-relations/'},
+                  {label: 'Relating Cards', link: '/cards/relations/relating-cards/'},
+                  {label: 'Relations vs. References', link: '/cards/relations/relations-vs-references/'},
+                ]
+              },
+
+              ]
+            },
           {
             label: "Task tracking",
             collapsed: true,

src/content/docs/cards/cards-overview.mdx

@@ -0,0 +1,46 @@
+---
+title: Introduction to Cards
+description: Learn how to leverage Cards for advanced knowledge management.
+---
+
+import { Image } from "astro:assets";
+import cards from "../../../assets/screenshots/huly/cards/cards.png";
+
+## Understanding Cards
+
+Cards are a flexible framework for structuring information efficiently. 
+
+While our initial implementation of Cards is focused on knowledge management, Cards will also serve as the foundation for many other features on the platform, including process management and threads. With Cards, you'll be able to build your own custom applications within Huly, such as a CRM, CMS, project management system and more.
+
+This guide explains the core components of the Cards system: **Types**, **Tags**, **Relations** and **Cards**, providing an overview of the entire system. We also have more in-depth guides on each element so you can learn how to use them in your own workspace, which are linked in the sections below.
+
+## Core elements of the Cards system
+
+The following elements make up the Cards system. Click on any guide to learn more:
+
+* [**Types**](/cards/types/types-overview) define the structure of information within the system. You can think of a Type like a blueprint with specific instructions for what details you'll need to store for each piece of information. 
+* [**Tags**](/cards/tags/tags-overview) are used to add additional properties or behaviors to a Type. Tags allow you to define a specific set of properties that can be applied to multiple Types.
+* [**Cards**](/cards/cards/creating-cards) are "instances" of a Type — the real information that you're storing in your knowledge management system. Each Card is a unique piece of information that follows the structure defined by its Type.
+* [**Relations**](/cards/relations/relations-overview) define the connections between different Types and Tags, allowing you to link related information together with Cards.
+
+## Using Cards for knowledge management
+
+Cards provide a structured and scalable way to organize knowledge. Unlike traditional document-based systems, where information can become scattered and difficult to navigate, Cards allow for dynamic connections, filtering, and categorization.
+
+This approach offers several advantages:
+
+* **Structured organization** - Each Card follows a defined Type, ensuring consistency.
+* **Easy navigation** - Relations between Cards create a web of interconnected knowledge, making it easy to find associated information.
+* **Scalability** - The modular nature of Cards allows you to expand your system at scale.
+* **Collaborative editing** - The rich text editor and activity tracking allow teams to work together collaboratively.
+
+Continue through the guides to learn how to put these concepts into practice, creating your own knowledge management system with Cards.
+
+<div style={{ height: "7px" }}></div>
+
+<div className="rounded-box">
+  <h5><strong>Let's build a game design system with Cards! 🎮</strong></h5>
+  <p>In the following guides, we'll look at how to design an adventure game system using Cards. Game designers need to store information about **game components**, **documents** and **files**, keeping track of how everything is connected. We'll use this example to illustrate how Cards can be used to create a comprehensive knowledge management system.</p>
+</div>
+
+<Image src={cards} alt="Cards sneak peek" inferSize quality="max" />

src/content/docs/cards/cards/creating-cards.mdx

@@ -0,0 +1,68 @@
+---
+title: Creating Cards
+description: Learn how to create Cards.
+---
+
+import { Image } from "astro:assets";
+import cardExampleNPC from "../../../../assets/screenshots/huly/cards/card-example-npc.png";
+
+<div className="rounded-box">
+  <h5><strong>What is a Card?</strong></h5>
+  <p>A Card is an instance of a Type, representing a specific piece of structured information. It follows the properties defined by its Type and can include rich text, attachments, relations, and tags, making it a flexible building block.</p>
+</div>
+
+To use Cards effectively in Huly, it’s important to first understand their relationship with Types. 
+
+Think of a **Type** as a blueprint and **Cards** as the structures built from that blueprint. If your blueprint defines a "house" as a structure with four windows and one door, then every house created from that blueprint will always have four windows and one door, regardless of color or furnishings.
+
+If you haven't already, check out our guide on [Creating Types](/cards/types/creating-types) — then return here to learn how to create Cards from the Types you've made.
+
+## Creating Cards
+
+Click `+ Create Card` in the top left corner of the Cards module.
+
+The following elements make up a Card:
+
+1. **Title** - a name for your Card
+2. **Type** - the Type that defines the properties of your Card (see [Creating Types](/cards/types/creating-types))
+4. **Properties** - the details of your Card, as defined by the Type
+5. **Rich text editor** - a collaborative text editing area that supports markdown formatting, images, tables and more
+6. **Children** - an area for adding child Cards (see [Parent-child Cards](/cards/cards/parent-child-cards))
+7. **Attachments** - an area for uploading files
+8. **Activity** - a log of all changes made to the Card and area for commenting
+
+> **Note:** Cards created from the `File` Type will have an additional area above the rich text editor for uploading files. To learn more about managing files with the `File` Type, see [File Types](/cards/types/file-types).
+
+Beyond these basic elements, Cards can also include:
+
+* **[Relations](/cards/relations/relations-overview)** - connections to other Cards
+* **[Tags](/cards/tags/tags-overview)** - optional properties that can be applied to Cards of different types
+
+Relations and Tags are set at the Type level. In other words, when you want to create a new Relation or Tag for a Card, you'll need to define this on the Type in Settings. To see how, check out these guides on [Defining Relations](/cards/relations/defining-relations) and [Creating Tags](/cards/tags/creating-tags).
+
+### Example: Creating an NPC Character Card
+
+To create a Card, first make sure you've selected the correct Type from the left side menu, then click the `+ Create Card` button. 
+
+From here, you can enter information in all of the attributes you [defined on your Type](/cards/types/creating-types). Below is an example of a Card for an NPC character in our **game design system**:
+
+<Image src={cardExampleNPC} alt="Example of an NPC Card" inferSize quality="max" />
+
+Note that this `NPC` Card has several [Relations](/cards/relations/relations-overview), defined on the `Character` Type from which it was derived:
+* **`Item`** - a `Character` possesses `Items`
+* **`Environment`** - a `Character` exists in an `Environment`
+* **`Game Narrative`** - a `Character` is included in a `Game Narrative`
+
+## Adding Card attribbutes
+
+To add an attribute to a Card, simply click the `+` icon next to the Type or Tag you want to add to. Adding a attribute on one Card will add the field to all existing Cards with that Type or Tag.
+
+## Learn more
+
+To further explore working with Cards, check out these guides:
+
+ * [Relating Cards](/cards/relations/relating-cards) - Define structured relationships between Cards.
+* [File Types](/cards/types/file-types) - Manage images, videos, PDFs, and other media within Huly's default `File` Type.
+* [Tags](/cards/tags/tags-overview) - Apply additional attributes across different Types.
+
+By understanding and structuring Cards effectively, you can build a powerful and flexible knowledge management system in Huly.

src/content/docs/cards/cards/parent-child-cards.mdx

@@ -0,0 +1,38 @@
+---
+title: Parent-child Cards
+description: Learn how to create parent-child Cards and their use cases.
+---
+
+import { Image } from "astro:assets";
+import parentChildCards from "../../../../assets/screenshots/huly/cards/parent-child-cards.png";
+import setParent from "../../../../assets/screenshots/huly/cards/set-parent.png";
+
+Cards can be connected through a parent-child relationship, where the child Card is best understood in the context of its parent Card. This is useful for creating a hierarchical structure of knowledge and information.
+
+## Creating a child Card
+
+To create a new child Card, click the `+ Create child` button on the parent Card. A new blank Card will be opened, where you can enter any information you want. The child Card will automatically be linked to the parent Card.
+
+## Connecting existing Cards as parent-child
+
+To connect an existing Card to a parent, right-click on the Card in the list or table view, or open the settings menu on the Card's page. Select `Set parent` from the list, then select a Card for the parent.
+
+<Image src={setParent} alt="Setting a parent Card" inferSize quality="max" />
+
+## Disconnecting parent-child Cards
+
+Any child Card can be disconnected from its parent by right-clicking or opening the settings menu and selecting `Unset parent`.
+
+## Parent-child vs. Relations
+
+While both Relations and parent-child connections allow you to link Cards, they serve different purposes and are used in distinct scenarios.
+
+Here are some general guidelines:
+
+* Use **parent-child** relationships when one entity (the "child") is dependent on another entity (the "parent") and logically belongs under it, or when a hierarchical structure is needed.
+
+* Use **[Relations](/cards/relations/relations-overview)** when both entities exist independently but need to be linked to reflect their interaction or connection. Relations don't imply a hierarchical structure, just that the entities are related in some way.
+
+<Image src={parentChildCards} alt="Example of parent-child cards" inferSize quality="max" />
+
+

src/content/docs/cards/cards/view-sort-filter-cards.mdx

@@ -0,0 +1,38 @@
+---
+title: View, sort and filter Cards
+description: Learn how to manage Cards with sorting, search and filtered views.
+---
+
+import { Image } from "astro:assets";
+import filterList from "../../../../assets/screenshots/huly/cards/filter-list.png";
+
+Viewing, sorting, and filtering Cards in the game design system allows you to manage complex, interrelated pieces of information more efficiently than plain documents in Huly. While documents are static and typically organized in a linear fashion, Cards offer a dynamic, flexible way to organize and access content based on various attributes, relationships, and tags. This approach enables you to quickly locate relevant information, prioritize tasks, and track connections Cards.
+
+## How Cards are organized
+
+In the Cards module, you'll notice that the left side navigation displays all of your Types. Cards are grouped together by Type, so you can easily view all Cards that share the same structure. Click on any Type in the sidebar to view its Cards.
+
+## Viewing Cards
+
+Within a Type, there are two ways to view Cards:
+
+##### Table view
+
+The table displays Cards in a spreadsheet-like format, with columns for each property defined by the Type.
+
+##### List view
+
+The list view displays Cards grouped by their Type. In list view, you can also group Cards by the user who created or modified them.
+
+## Sorting Cards
+
+In the table view, you can sort most columns by clicking on the column heading. Use the toggle icon to further customize the view by selecting which columns to display in the table.
+
+## Creating filtered view
+
+Click the `Filter` button to create a view with specific criteria. You can filter Cards by as many criteria as you like.
+
+<Image src={filterList} alt="Filtering a list of Cards" inferSize quality="max" />
+
+To save your filtered view for easy access later, click `Save as` and enter a name for your filtered view. Your view will be saved to the sidebar, where you can then select whether to make it public (visible to others) or private (visible only to you).
+

src/content/docs/cards/relations/defining-relations.mdx

@@ -0,0 +1,65 @@
+---
+title: Defining Relations
+description: Learn how to define Relations between Types.
+---
+
+import { Image } from "astro:assets";
+import relationsDialog from "../../../../assets/screenshots/huly/cards/relations-dialog.png";
+import characterRelations from "../../../../assets/screenshots/huly/cards/character-relations.png";
+
+To define Relations between Types, navigate to Settings and open the Type you want to add a Relation to. Click the `+` button in the Relations area.
+
+<Image src={relationsDialog} alt="Adding a Relation" inferSize quality="max" />
+
+## Naming Relations
+
+When defining a Relation, you'll need to give it a clear and descriptive name on both sides. The names should be human-readable and indicate the nature of the relationship between the two entities.
+
+Let's look at some examples of Relations on our `Character` Type:
+
+* **Possessed by** (`Character`) - **Possesses** (`Item`)
+  * *Meaning: A Character **possesses** an Item; an Item is **possessed by** a Character.*
+
+
+* **Inhabited by** (`Character`) - **Exists in** (`Environment`)
+  * *Meaning: A Character **exists in** an Environment; an Environment is **inhabited by** a Character.*
+
+
+* **Features** (`Character`) - **Included in** (`Game Narrative`)
+  * *Meaning: A Character is **included in** a Game Narrative; a Game Narrative **features** a Character*
+
+These names describe how two Types are connected, allowing the system to establish their relationships clearly and logically.
+
+<Image src={characterRelations} alt="Relations on the Character Type" inferSize quality="max" />
+
+## Selecting the kind of Relation
+
+When creating a Relation, you must specify the kind of relationship between the entities. There are three kinds to choose from:
+
+#### 1:1 Relation
+**Definition**: One entity of the first type is related to exactly one entity of the second type.
+
+**Example**: An `Item` has only one `Audio Asset`, and an `Audio Asset` is only used by one Item.
+
+**Use case**: This type of relation is ideal for cases where a single instance of one entity is paired with a single instance of another. For instance, each `Item` may have a unique `Audio Asset` associated with it.
+
+#### 1:N Relation
+**Definition**: One entity of the first type is related to multiple entities of the second type.
+
+**Example**: A `Quest` can have multiple `Objectives`, but each `Objective` belongs to only one `Quest`.
+
+**Use case**: This relation type is commonly used when a single entity (like a `Quest`) can be linked to multiple related entities (like `Objectives`), but each related entity (an `Objective`) is only connected to that one instance of the first entity.
+
+#### N:N Relation
+
+**Definition**: Multiple entities of the first type are related to multiple entities of the second type.
+
+**Example**: A `Character` can have multiple `Items`, and an `Item` can be used by multiple `Characters`.
+
+**Use case**: This relation type is useful when many instances of one entity (e.g., `Character`) can be associated with many instances of another entity (e.g., `Items`). It reflects a more dynamic, interconnected system, like a character inventory or shared assets.
+
+By defining clear and meaningful Relations between your Types, you can create a system where entities are connected in ways that mirror their real-world interactions. This adds depth to your data structure, making it easier to navigate, manage, and scale as your system grows.
+
+## Using Relations with Cards
+
+Check out our guide on [Relating Cards](/cards/relations/relating-cards) to learn how to connect Cards using the Relations you've defined.

src/content/docs/cards/relations/relating-cards.mdx

@@ -0,0 +1,31 @@
+---
+title: Relating Cards
+description: Learn how to connect Cards by Relations.
+---
+
+import { Image } from "astro:assets";
+import characterRelationsCard from "../../../../assets/screenshots/huly/cards/character-relations-card.png";
+
+After setting up [Relations](/cards/relations/defining-relations), you can start relating Cards to each other.
+
+Navigate to any Card created from a Type that has Relations. Near the bottom of the Card, you'll find all of the Relations you defined in Settings.
+
+## Adding a Relation
+
+Click the `+` button to add a Card. You'll see a dropdown menu of all available Cards of the related Type. Select a Card to establish the connection.
+
+In our **game design** example, we've defined Relations between `Character`, `Item`, `Environment` and `Game Narrative` Types. Here, we can see the name of each Relation and all of its related Cards.
+
+<Image src={characterRelationsCard} alt="Relations on a Character Card" inferSize quality="max" />
+
+> **Note:** It is currently possible to create a relation to a Person or Company in your Huly workspace. Soon, Persons will be replaced with Cards, allowing you to seamlessly manage your contacts within the Cards system.
+
+## Removing a Relation
+
+To remove a related Card, simply right-click on the Card name and select `Remove relation`. This will break the connection between the two Cards.
+
+To delete the Relation entirely, navigate back to Settings, open the Relation and click the trash icon. This will break the relations for all associated Cards.
+
+## Parent-child Cards
+
+In some cases you may want to connect parent-child Cards instead of using Relations. For more on this, see [Parent-child Cards](/cards/cards/parent-child-cards).