diff --git a/.gitignore b/.gitignore index 2d33b96..f6264fc 100644 --- a/.gitignore +++ b/.gitignore @@ -21,3 +21,5 @@ pnpm-debug.log* # macOS-specific files .DS_Store + +!src/content/docs/cards/tags/ \ No newline at end of file diff --git a/astro.config.mjs b/astro.config.mjs index 59dedc1..0c9884f 100644 --- a/astro.config.mjs +++ b/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, diff --git a/src/assets/screenshots/huly/cards/audio-asset.png b/src/assets/screenshots/huly/cards/audio-asset.png new file mode 100644 index 0000000..60a9437 Binary files /dev/null and b/src/assets/screenshots/huly/cards/audio-asset.png differ diff --git a/src/assets/screenshots/huly/cards/blank-file-card.png b/src/assets/screenshots/huly/cards/blank-file-card.png new file mode 100644 index 0000000..331ced0 Binary files /dev/null and b/src/assets/screenshots/huly/cards/blank-file-card.png differ diff --git a/src/assets/screenshots/huly/cards/card-example-npc.png b/src/assets/screenshots/huly/cards/card-example-npc.png new file mode 100644 index 0000000..f2e5bff Binary files /dev/null and b/src/assets/screenshots/huly/cards/card-example-npc.png differ diff --git a/src/assets/screenshots/huly/cards/cards-spaces.png b/src/assets/screenshots/huly/cards/cards-spaces.png new file mode 100644 index 0000000..10b6f24 Binary files /dev/null and b/src/assets/screenshots/huly/cards/cards-spaces.png differ diff --git a/src/assets/screenshots/huly/cards/cards.png b/src/assets/screenshots/huly/cards/cards.png new file mode 100644 index 0000000..8842c64 Binary files /dev/null and b/src/assets/screenshots/huly/cards/cards.png differ diff --git a/src/assets/screenshots/huly/cards/character-item-ref-card.png b/src/assets/screenshots/huly/cards/character-item-ref-card.png new file mode 100644 index 0000000..ff86f3b Binary files /dev/null and b/src/assets/screenshots/huly/cards/character-item-ref-card.png differ diff --git a/src/assets/screenshots/huly/cards/character-item-ref-settings.png b/src/assets/screenshots/huly/cards/character-item-ref-settings.png new file mode 100644 index 0000000..3c20697 Binary files /dev/null and b/src/assets/screenshots/huly/cards/character-item-ref-settings.png differ diff --git a/src/assets/screenshots/huly/cards/character-item-relation.png b/src/assets/screenshots/huly/cards/character-item-relation.png new file mode 100644 index 0000000..42faf10 Binary files /dev/null and b/src/assets/screenshots/huly/cards/character-item-relation.png differ diff --git a/src/assets/screenshots/huly/cards/character-relations-card.png b/src/assets/screenshots/huly/cards/character-relations-card.png new file mode 100644 index 0000000..dcab3be Binary files /dev/null and b/src/assets/screenshots/huly/cards/character-relations-card.png differ diff --git a/src/assets/screenshots/huly/cards/character-relations.png b/src/assets/screenshots/huly/cards/character-relations.png new file mode 100644 index 0000000..3acf6b9 Binary files /dev/null and b/src/assets/screenshots/huly/cards/character-relations.png differ diff --git a/src/assets/screenshots/huly/cards/create-enum.png b/src/assets/screenshots/huly/cards/create-enum.png new file mode 100644 index 0000000..f1f8028 Binary files /dev/null and b/src/assets/screenshots/huly/cards/create-enum.png differ diff --git a/src/assets/screenshots/huly/cards/derived-types.png b/src/assets/screenshots/huly/cards/derived-types.png new file mode 100644 index 0000000..548239c Binary files /dev/null and b/src/assets/screenshots/huly/cards/derived-types.png differ diff --git a/src/assets/screenshots/huly/cards/filter-list.png b/src/assets/screenshots/huly/cards/filter-list.png new file mode 100644 index 0000000..0232a39 Binary files /dev/null and b/src/assets/screenshots/huly/cards/filter-list.png differ diff --git a/src/assets/screenshots/huly/cards/game-asset-types.png b/src/assets/screenshots/huly/cards/game-asset-types.png new file mode 100644 index 0000000..93545e4 Binary files /dev/null and b/src/assets/screenshots/huly/cards/game-asset-types.png differ diff --git a/src/assets/screenshots/huly/cards/image-asset.png b/src/assets/screenshots/huly/cards/image-asset.png new file mode 100644 index 0000000..91a7241 Binary files /dev/null and b/src/assets/screenshots/huly/cards/image-asset.png differ diff --git a/src/assets/screenshots/huly/cards/item-character-relation.png b/src/assets/screenshots/huly/cards/item-character-relation.png new file mode 100644 index 0000000..f6d7785 Binary files /dev/null and b/src/assets/screenshots/huly/cards/item-character-relation.png differ diff --git a/src/assets/screenshots/huly/cards/parent-child-cards.png b/src/assets/screenshots/huly/cards/parent-child-cards.png new file mode 100644 index 0000000..d6e7109 Binary files /dev/null and b/src/assets/screenshots/huly/cards/parent-child-cards.png differ diff --git a/src/assets/screenshots/huly/cards/relations-dialog.png b/src/assets/screenshots/huly/cards/relations-dialog.png new file mode 100644 index 0000000..fd82441 Binary files /dev/null and b/src/assets/screenshots/huly/cards/relations-dialog.png differ diff --git a/src/assets/screenshots/huly/cards/set-parent.png b/src/assets/screenshots/huly/cards/set-parent.png new file mode 100644 index 0000000..250c661 Binary files /dev/null and b/src/assets/screenshots/huly/cards/set-parent.png differ diff --git a/src/assets/screenshots/huly/cards/sound-effect-card.png b/src/assets/screenshots/huly/cards/sound-effect-card.png new file mode 100644 index 0000000..664bc33 Binary files /dev/null and b/src/assets/screenshots/huly/cards/sound-effect-card.png differ diff --git a/src/assets/screenshots/huly/cards/tag-properties-flying.png b/src/assets/screenshots/huly/cards/tag-properties-flying.png new file mode 100644 index 0000000..d5087a7 Binary files /dev/null and b/src/assets/screenshots/huly/cards/tag-properties-flying.png differ diff --git a/src/assets/screenshots/huly/cards/tag-properties-wizard.png b/src/assets/screenshots/huly/cards/tag-properties-wizard.png new file mode 100644 index 0000000..994c529 Binary files /dev/null and b/src/assets/screenshots/huly/cards/tag-properties-wizard.png differ diff --git a/src/assets/screenshots/huly/cards/tags-settings.png b/src/assets/screenshots/huly/cards/tags-settings.png new file mode 100644 index 0000000..4eaeeaa Binary files /dev/null and b/src/assets/screenshots/huly/cards/tags-settings.png differ diff --git a/src/assets/screenshots/huly/cards/tags.png b/src/assets/screenshots/huly/cards/tags.png new file mode 100644 index 0000000..e34da32 Binary files /dev/null and b/src/assets/screenshots/huly/cards/tags.png differ diff --git a/src/assets/screenshots/huly/cards/types-overview.png b/src/assets/screenshots/huly/cards/types-overview.png new file mode 100644 index 0000000..abea390 Binary files /dev/null and b/src/assets/screenshots/huly/cards/types-overview.png differ diff --git a/src/content/docs/cards/cards-overview.mdx b/src/content/docs/cards/cards-overview.mdx new file mode 100644 index 0000000..c4bab3c --- /dev/null +++ b/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. + +
+ +
+
Let's build a game design system with Cards! ๐ŸŽฎ
+

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.

+
+ +Cards sneak peek diff --git a/src/content/docs/cards/cards/creating-cards.mdx b/src/content/docs/cards/cards/creating-cards.mdx new file mode 100644 index 0000000..a78e2c1 --- /dev/null +++ b/src/content/docs/cards/cards/creating-cards.mdx @@ -0,0 +1,79 @@ +--- +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"; +import cardsSpaces from "../../../../assets/screenshots/huly/cards/cards-spaces.png"; + +
+
What is a Card?
+

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.

+
+ +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 a space + +A space is like a container for your Cards. You can set permissions at the space level to determine who can access the Cards within that space. + +To create a new space, click the `+ Create Space` button in the top left corner of the Cards module. Here, you can enter a name, select they Types that will be used in that space, and set owners, members and privacy settings. Setting the space to "Private" will prevent anyone other than the members listed from accessing the Cards in that space. + +Creating a Cards space + +Spaces for Cards act like any other space in Huly, meaning you can leave, join and archive spaces, and global admin roles will apply. For more on managing permissions at the workspace and space level, see our guide on [Roles and Permissions](../../../advanced-settings/roles). + +## 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**: + +Example of an NPC Card + +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. \ No newline at end of file diff --git a/src/content/docs/cards/cards/parent-child-cards.mdx b/src/content/docs/cards/cards/parent-child-cards.mdx new file mode 100644 index 0000000..0961174 --- /dev/null +++ b/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. + +Setting a parent Card + +## 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. + +Example of parent-child cards + + diff --git a/src/content/docs/cards/cards/view-sort-filter-cards.mdx b/src/content/docs/cards/cards/view-sort-filter-cards.mdx new file mode 100644 index 0000000..614f657 --- /dev/null +++ b/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. + +Filtering a list of Cards + +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). + diff --git a/src/content/docs/cards/relations/defining-relations.mdx b/src/content/docs/cards/relations/defining-relations.mdx new file mode 100644 index 0000000..89348c1 --- /dev/null +++ b/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. + +Adding a Relation + +## 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. + +Relations on the Character Type + +## 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. \ No newline at end of file diff --git a/src/content/docs/cards/relations/relating-cards.mdx b/src/content/docs/cards/relations/relating-cards.mdx new file mode 100644 index 0000000..694cc7e --- /dev/null +++ b/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. + +Relations on a Character Card + +> **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). \ No newline at end of file diff --git a/src/content/docs/cards/relations/relations-overview.mdx b/src/content/docs/cards/relations/relations-overview.mdx new file mode 100644 index 0000000..98f9010 --- /dev/null +++ b/src/content/docs/cards/relations/relations-overview.mdx @@ -0,0 +1,19 @@ +--- +title: What are Relatons? +description: Learn about Relations in the Cards system. +--- + +
+
What is a Relation?
+

A Relation defines a connection between Cards, linking information across the system. Relations are created between Types in Settings before any Cards exist, establishing predefined associations. Once Cards are created, they can be connected through these Relations, forming a structured and interconnected knowledge base.

+
+ +Relations allow you to connect Cards and define their interactions in a way that reflects real-world relationships. This allows you to: + +* **Build networks of interconnected data** - Relations help create a web of linked information, allowing you to easily explore how various entities relate to one another. This interconnectedness makes it possible to visualize complex systems and understand the structure of information. +* **Optimize data navigation** - Relations make it easy to navigate between associated Cards, making it easier to find relevant information quickly. + +In our **game design** example, a `Character` Card may be related to an `Item` Card that the character posesses, or a `Game Asset` Card could be related to a `Game Component` that it's used for. + +To learn how these relationships work in practice, check out our guides on [Defining Relations](/cards/relations/defining-relations) and [Relating Cards](/cards/relations/relating-cards). + diff --git a/src/content/docs/cards/relations/relations-vs-references.mdx b/src/content/docs/cards/relations/relations-vs-references.mdx new file mode 100644 index 0000000..575dfb5 --- /dev/null +++ b/src/content/docs/cards/relations/relations-vs-references.mdx @@ -0,0 +1,71 @@ +--- +title: Relations vs. References +description: Learn the differences between Relations and References and best use cases for each. +--- + +import { Image } from "astro:assets"; +import characterItemRelation from "../../../../assets/screenshots/huly/cards/character-item-relation.png"; +import itemCharacterRelation from "../../../../assets/screenshots/huly/cards/item-character-relation.png"; +import characterItemRefSettings from "../../../../assets/screenshots/huly/cards/character-item-ref-settings.png"; +import characterItemRefCard from "../../../../assets/screenshots/huly/cards/character-item-ref-card.png"; + +In some cases, you may want to connect Cards together using References instead of Relations. + +Relations are bi-directional, meaning that a Relation will appear on both Cards involved the relationship. In our example of a `Character` possessing an `Item`, the Relation will appear on both the `Character` and the `Item` Card. + +> **Below:** The `Item` is shown on the `Character` Card + +Character Card + +> **Below:** The `Character` is shown on the `Item` Card + +Item Card + +References, on the other hand, are one-directional. A Reference will only appear on the ***Referring*** Card, and a Reference is a type of attribute. Instead of using a Relation to define the association between `Character` and `Item`, you can add a Reference attribute to the `Character` Type that references the `Item` Type. This can be a single-select or multi-select attribute, depending on your use case. In this case, the `Item` Card will not show which `Character` possesses it. + +> **Below:** Add a reference attribute to the `Character` Type in Settings + +Setting a reference attribute on a Type + +> **Below:** Select `Item` Cards on the `Character` Card using the Reference attribute + +Using a reference attribute on a Card + +## Deciding whether to use a Relation or Reference + +The decision to use a Relation or Reference depends on your use case and how you'd like to design your own system. Here are a few things to consider with regard to functionality and presentation of your data. + +> **Note:** We will diverge here from our game design example to illustrate the difference between Relations and References using a more general example of `Person` and `Meeting`. Soon, Persons in Huly will be replaced with Cards, allowing you to manage your contacts in a more robust and customized database system. The examples in this section demonstrate the differences between Relations and References on a large scale, considering a case of a team managing thousands of contacts and meetings. + +##### Visibility and navigation + +Relations are visible on both Cards, making it easy to navigate between related entities. This bi-directional visibility is useful when you want to maintain a clear and reciprocal connection between two entities. For example, if you have a `Person` that is related to a `Meeting`, both the `Person` Card and the `Meeting` Card will show this relationship, allowing easy navigation in both directions. + +##### Scalability + +As your system grows, consider how each option will scale. + +For example, let's say you want to create Cards for **meeting minutes**. You may want to create a Relation: + +- `Meeting` N:N `Person` + * **Attended** (`Meeting`) - **Attendees** (`Person`) + * *Meaning: A Meeting has **attendees**; a Person **attended** Meetings.* + +This may seem convenient at first โ€” you can see all of the attendees in the Relations section of each `Meeting` Card, and you can see which meetings everyone attended on the `Person` Cards. + +However, as the number of meetings grows, each `Person` may end up with an overwhelming number of meetings on their Card, making it difficult to navigate. In this case, a better solution might be to use a Reference attribute on the `Meeting` Type; for example: + +- **`Meeting Minutes`** (Type) + - Date + - Topic + - Attendees (Reference to `Person`) + +In this case, you can add many `Person` Cards to the `Meeting` Card without cluttering the `Person` Cards themselves. + +##### Sorting and filtering + +References are a type of attribute, so you can sort and filter your Cards based on the Reference value. If you might want to sort or filter your Cards by a specific attribute, consider using a Reference instead of a Relation. In our example of `Person` and `Meeting`, if `Person` is a Reference attribute on the `Meeting` Type, you can easily create filtered views for meetings attended by different groups of people. + +## Designing your own knowledge system + +Ultimately, how you design your system is up to you! There are advantages and disadvanteges to every kind of setup, and there's no "correct" way other than the way that works best for you. \ No newline at end of file diff --git a/src/content/docs/cards/tags/applying-tags.mdx b/src/content/docs/cards/tags/applying-tags.mdx new file mode 100644 index 0000000..f09e710 --- /dev/null +++ b/src/content/docs/cards/tags/applying-tags.mdx @@ -0,0 +1,21 @@ +--- +title: Applying Tags to Cards +description: Learn how to apply Tags to Cards. +--- + +import { Image } from "astro:assets"; +import tags from "../../../../assets/screenshots/huly/cards/tags.png"; + +Now that we've learned about [Tags](/cards/tags/tags-overview) and how to [create](/cards/tags/creating-tags) them, let's explore how to apply them to our Cards. First, you'll need to create a Card from a Type that has Tags. If you haven't already, check out our guides on [creating Cards](/cards/cards/creating-cards). + +## Adding a Tag to a Card + +To add a Tag to a Card, click the `+` icon beside the Type. You'll be able to select from any Tags that have been created for that Type. + +Adding a Tag to a Card + +For our **game design** example, we're applying the `Flying` and `Wizard` Tags to an `Enemy` Card (derived from `Game Component` / `Character` / `Enemy` Types). These Tags provide additional properties that define how the character interacts with the game. + +## Removing a Tag from a Card + +To remove a Tag from a Card, simply click the `x` icon beside the Tag name. This will remove the Tag and all its associated properties from the Card. \ No newline at end of file diff --git a/src/content/docs/cards/tags/creating-tags.mdx b/src/content/docs/cards/tags/creating-tags.mdx new file mode 100644 index 0000000..0e26b34 --- /dev/null +++ b/src/content/docs/cards/tags/creating-tags.mdx @@ -0,0 +1,28 @@ +--- +title: Creating Tags +description: Learn how to create Tags. +--- + +import { Image } from "astro:assets"; +import tagPropertiesFlying from "../../../../assets/screenshots/huly/cards/tag-properties-flying.png"; +import tagPropertiesWizard from "../../../../assets/screenshots/huly/cards/tag-properties-wizard.png"; + +In the previous guide, we learned about Tags and how they can be used to define behaviors or attributes that extend a Cardโ€™s functionality. Now, let's put that knowledge into practice and create some Tags. + +## Creating a Tag + +Navigate to Settings and select the Type you want to add Tags to; then, click the `+` button in the Tags area. Add a name for your Tag and click `Create`. + +## Adding Tag properties + +Click on any Tag to open it. To add a property to a Tag, click the `+` button in the properties section. Adding properties to a Tag is the same as adding properties to a Type (see [this guide](/cards/types/creating-types/#adding-properties)). These properties will only be available on Cards using that Tag. + +In our **game design** example, we've added a custom property "Flying speed" that exists on the `Flying` Tag: + +Tag properties + +To the `Wizard` Tag, we've added a property "mana": + +Tag properties + +Check out the next guide on [Applying Tags](/cards/tags/applying-tags) to learn how to use this Tag on a Card. \ No newline at end of file diff --git a/src/content/docs/cards/tags/tags-overview.mdx b/src/content/docs/cards/tags/tags-overview.mdx new file mode 100644 index 0000000..27bc84c --- /dev/null +++ b/src/content/docs/cards/tags/tags-overview.mdx @@ -0,0 +1,27 @@ +--- +title: What are Tags? +description: Learn about Tags in the Cards system. +--- + +import { Image } from "astro:assets"; +import tagsSettings from "../../../../assets/screenshots/huly/cards/tags-settings.png"; + +
+
What is a Tag?
+

A Tag is a set of additional properties that can be applied to a Card, allowing you to define behaviors or attributes that extend a Cardโ€™s functionality. Tags provide flexibility by enabling shared properties across different Types without requiring new Types.

+
+ +We've seen how we can [create variations of a Type](/cards/types/creating-types/#creating-derived-types). But what if we want to define some kind of behavior or functionality without altering the core structure of the Type itself? + +Tags allow you to add multiple additional attributes to a single Card. In our game design example, we can create Tags like `Flying` and `Wizard` added to the `Character` Type, so any `Character` Card we create could have access to these attributes: + +Tags Settings + +In our next guide, we'll learn how to create the Tags we just described. Check out [Creating Tags](/cards/tags/creating-tags) to get started! + +## Tags vs. Types +> *__But wait__, couldn't I just create separate Types for Flying Characters and Wizards?* + +**Yes, you absolutely can!** Creating separate Types for each variation is a valid approach. However, the benefit of using Tags is flexibility โ€” you donโ€™t need to create a new Type for every possible combination of behaviors or attributes. Instead, Tags allow you to mix and match properties based on the unique needs of each Card. On the other hand, creating new Types might be more appropriate if the differences between variations are fundamental to the design or behavior of the Card. + +Both methods have their pros and cons. Itโ€™s up to you, as the system designer, to experiment and choose the approach that best suits your needs. diff --git a/src/content/docs/cards/types/creating-types.mdx b/src/content/docs/cards/types/creating-types.mdx new file mode 100644 index 0000000..72b6c8b --- /dev/null +++ b/src/content/docs/cards/types/creating-types.mdx @@ -0,0 +1,86 @@ +--- +title: Creating Types +description: Learn how to create Types. +--- + +import { Image } from "astro:assets"; +import typesOverview from "../../../../assets/screenshots/huly/cards/types-overview.png"; +import createEnum from "../../../../assets/screenshots/huly/cards/create-enum.png"; +import derivedTypes from "../../../../assets/screenshots/huly/cards/derived-types.png"; + +To create a Type, navigate to Settings, find `TYPES` in the left side menu, and click the `+` button that appears when hovering over the header. Enter a name for your Type and click `Create`. + +Overview of Types settings + +## Adding properties + +Next, add some properties for your Type. **Properties** are anything that will be shared by all Cards of this Type. + +To add a property, click the `+` button in the properties section. Select from the following: + +* URL +* Text +* Checkbox +* Number +* Date +* Reference (link to an Object in your workspace) +* Multi-select (select multiple Objects or dropdown values) +* Select (select one dropdown value) + +In our example, we know that all Game Components will have a `Name` and `Description`, so we'll add these on the `Game Component` Type as `Text` properties. + +> **Note:** Properties can also be added directly to Cards โ€” see [Creating Cards](/cards/cards/creating-cards). + +##### Creating dropdown menus (enums) + +If you chose to add a property of type "Multi-select" or "Select", you can create a dropdown menu with options. Click the `+` button to add a new select menu (called an "**enum**"). Enter a title and options for the menu and click `Save`. Then, select your menu from the "Select" dropdown to use it for this property. + +In our example, we've created a Type `Character` and added a "Multi-select" property `Movement modes` with a dropdown menu of options: `๐Ÿƒ Ground`, `๐Ÿฆ… Air`, and `๐ŸŒŠ Water`: + +Creating an enum + +## Creating derived Types + +We mentioned that the `Game Component` Type will have a "Name" and "Description" property. But what if we want to create different kinds of `Game Components`, each with their own unique properties? + +Types can be derived from other Types to define variations that have their own unique properties. To create a derived Type, find the `TYPES` section on the main Type page and click the `+` button. + +From here, the steps for creating a derived Type are the same as creating any other Type. Note that the derived Type will automatically inherit all properties of the Type from which it was derived. + +In our example, we can derive several new Types from the `Game Component` Type, such as `Character`, `Item` and `Environment`, each with their own set of properties. + +We can create as many levels of derivation as is needed. In the example below, we've derived Types `Player`, `Enemy` and `NPC` from Type `Character`. + +Derived Types + +We can define properties on each Type, like this: + +- **`Game Component`** + - Name + - Description + - **`๐Ÿ˜ถ Character`** + - Speed (m/s) + - Jump height (m) + - Movement modes (ground, air, water) + - Max health + - Stamina + - **`๐Ÿคบ Player`** + - Abilities (jump, attack, talk, etc.) + - XP + - **`๐Ÿ‘ฟ Enemy`** + - Attack patterns (claw swipe, fireball, charge attack) + - **`๐Ÿง‘ NPC`** + - Affiliation (friendly, neutral, hostile) + - Essential? (yes/no) + - Respawn? (yes/no) + - **`๐ŸŽ’ Item`** + - Item type (weapon, consumable, key item) + - Effect + - Rarity (common, rare, legendary) + - **`๐ŸŒŽ Environment`** + - Size (small, medium, large) + - Interactive? (yes/no) + +## Deleting a Type + +To delete a Type, navigate to the Type page in Settings and click the trash icon in the top right corner. Note that deleting a Type will also delete all Cards of that Type, and this action cannot be undone. \ No newline at end of file diff --git a/src/content/docs/cards/types/file-types.mdx b/src/content/docs/cards/types/file-types.mdx new file mode 100644 index 0000000..8c11704 --- /dev/null +++ b/src/content/docs/cards/types/file-types.mdx @@ -0,0 +1,75 @@ +--- +title: File Types +description: Learn how to manage Files using the default File Type. +--- + +import { Image } from "astro:assets"; +import blankFileCard from "../../../../assets/screenshots/huly/cards/blank-file-card.png"; +import gameAssetTypes from "../../../../assets/screenshots/huly/cards/game-asset-types.png"; +import audioAsset from "../../../../assets/screenshots/huly/cards/audio-asset.png"; +import imageAsset from "../../../../assets/screenshots/huly/cards/image-asset.png"; +import soundEffectCard from "../../../../assets/screenshots/huly/cards/sound-effect-card.png"; + +The Huly Cards system comes with a special default Type called **`File`**. This basic Type allows you to manage files, such as images, videos, PDFs and other media. + +The `File` Type behaves the same as any other Type, with a few key differences: + +1. The `File` Type **cannot be deleted**. +2. Cards created from the `File` Type (or derivations of the `File` Type) include a **designated area for uploading files**. + +File Card + +You can think of the `File` Type as the foundation for an advanced file drive system. Rather than uploading files to a single drive and organizing them into folders, you can create a Type for each category of files you want to manage and define their shared properties. + +## Deriving Types from `File` + +To create new Types derived from `File`, navigate to Settings, select `File` under `TYPES` in the left sidebar, and click the `+` button in the `Types` area. + +Creating a Type derived from `File` the same as creating any other derived Type (see steps for [creating derived Types](/cards/types/creating-types/#creating-derived-types)). + +In our **game design** example, we'll create two Types derived from `File` to manage different categories of game assets, each with their own properties: + +- **`File`** + - **`Game Asset`** + - Name + - Description + - Formats + - **`๐Ÿ–ผ๏ธ Image Asset`** + - Dimensions (px) + - Transparency? (yes/no) + - **`๐Ÿ”Š Audio Asset`** + - Purpose (soundtrack, sound effect) + - Duration (s) + - Looping? (yes/no) + +Types derived from Game Asset +Image asset properties +Audio asset properties + +## Creating Cards from `File` Types + +Creating Cards from `File` Types is the same as creating Cards from any other Type (see our guide for [Creating Cards](/cards/cards/creating-cards)) โ€” when you create a Card from a `File` Type, however, you'll see a designated area for uploading files. + +Here, you can click the upload button or drop your files into the upload area. + + Below is an example of a Card created from the `Audio Asset` Type: + +Sound effect Card + +> **WARNING:** Once uploaded, a file **cannot be deleted** from the Card. + +## Tips for using the `File` Type + +The `File` Type is a powerful tool for managing files in your Huly workspace. Here are some tips for getting the most out of it: + +* **Create your custom file system** - Create different Types for various categories of files to ensure everything is neatly organized in one place. +* **Collaborate on media assets** - Use the `File` Type to store media that you may need to discuss with the team or add context to within the editor. +* **[Relations](/cards/relations/relations-overview)** - Link your files to other Cards in your knowledge management system to establish connections between related resources. +* **Track metadata** - Define useful properties for each Type, such as dimensions, duration, or format, to make it easier to filter and organize files based on their characteristics. + +## Other ways to connect files to Cards +In addition to using the `File` Type, there are several other ways to link files and media to Cards. There are advantages to each method, so choose the combination that works best for you! + +* **Card attachments** - Attach files to any Card, regardless of its Type, by adding them directly to the Cardโ€™s interface (see [Creating Cards](/cards/cards/creating-cards) for an example). This is a great way to quickly attach a file that doesn't need its own dedicated Card. +* **Inline embeds** - Use the `/` shortcut in the collaborative editor to embed images directly within the content. This is useful for adding visual elements to text-based Cards. +* **Comment attachments** - You can also attach files to specific comments within the activity section, which is handy when you need to send a resource or snapshot with your message. \ No newline at end of file diff --git a/src/content/docs/cards/types/types-overview.mdx b/src/content/docs/cards/types/types-overview.mdx new file mode 100644 index 0000000..49fddbf --- /dev/null +++ b/src/content/docs/cards/types/types-overview.mdx @@ -0,0 +1,21 @@ +--- +title: What are Types? +description: Learn about Types as part of the Cards system. +--- + +
+
What is a Type?
+

A Type is a blueprint that defines the structure and properties of a Card. It specifies the attributes each Card will have, ensuring consistency and organization across the system. Types can also be derived to create variations with unique properties.

+
+ +Types define the structure of information within the system. Think of a Type as a blueprint that outlines the specific details you'll need to store for each piece of information. + +In our **game design** example, we have three core Types: + +2. **`Game Component`** - Physical or digital elements in the game world +3. **`Document`** - Written design, technical and narrative information. This is a default system `Document` Type. +4. **`File`** - Digital files used in the game, such as images, sounds, textures and 3D models. This is a default system `File` Type (see [File Types](/cards/types/file-types)). + +Each **Type** has a set of **properties** that define the specific details we want to capture for each piece of information. + +We can also derive Types to define variations that have their own unique properties. To learn how to create Types and derived Types in practice, check out our next guide on [Creating Types](/cards/types/creating-types). \ No newline at end of file diff --git a/src/styles.css b/src/styles.css index e8a0899..f06546d 100644 --- a/src/styles.css +++ b/src/styles.css @@ -11,6 +11,7 @@ --sl-color-gray-5: #383838; --sl-color-gray-6: #1A1928; --sl-color-black: #242839; + --rounded-box-bg:rgb(39, 57, 92); } /* Light mode colors. */ :root[data-theme='light'] { @@ -26,6 +27,7 @@ --sl-color-gray-6: #eeeeee; --sl-color-gray-7: #DDE4F6; --sl-color-black: #ffffff; + --rounded-box-bg:rgb(231, 237, 250); } [data-icon] { @@ -46,4 +48,11 @@ .social-icons span { display: inline-block; padding: 0 7px; +} + +.rounded-box { + background-color: var(--rounded-box-bg); + border-radius: 12px; + padding: 20px; + transition: background-color 0.3s ease-in-out; } \ No newline at end of file