GH-447 [DRAFT] begginer-friendly documentation

content/docs/en/contributing/translate.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Translate"
 description: "How to translate HytaleModding to your language"
+icon: Languages
 ---
 
 # Translating HytaleModding
@@ -60,10 +61,12 @@ icon: Globe
 ```
 ---
 
+{/* crowdin-ignore-start */}
 {/* 
 For translators who will edit this page:
 
 - You are required to translate the Guidelines as they change.
 - General guidelines should be translated but not edited.
-- Learn how to use Markdown from writing_guides.mdx
-*/}
+- Learn how to use Markdown from [Writing Guides](.contributing/writing_guides)
+*/}
+{/* crowdin-ignore-end */}

content/docs/en/contributing/writing-guides.mdx

@@ -25,6 +25,7 @@ description: "Learn the basics of Java programming."
 authors:
     - name: "Your Name"
       url: "https://yourwebsite.com"
+icon: YourIcon 
 ---
 ```
 
@@ -57,6 +58,37 @@ We use [Markdown](https://www.markdownguide.org/) for formatting our guides. Her
 
 This is the same type of formatting you'll see on most documentation websites, and also social media platforms like Discord. 
 
+### Links
+Everyone knows what a link is. However, there is a difference between linking to an external resource and linking to an internal one.
+
+In general, in Markdown they are written like this: `[Your Text](Your link)`
+
+#### External
+
+Nothing to explain, just `https://example.com`.
+
+#### Internal
+
+You cannot use regular links here. Let's say your link to another guide is `https://hytalemodding.dev/en/docs/quick-start`. 
+You can't write it like that because you are not only referring to the page but also to the language, which is not correct.
+Instead, type `./quick-start` which is correct and links to the page in the user's language. 
+
+**Accessing files**
+
+- **Current Folder**: `./`
+- **Folder above**: `../` as many times as this folder is higher in the hierarchy.
+
+## Icons
+
+If you want to add an icon for your page then you should use [Lucide](https://lucide.dev/).
+
+1. Go to the [site](https://lucide.dev/) and find an icon you like.
+2. Once you have selected an icon, click on it, then click "See in action"
+3. Next, click on "React" which we are using. Next, click on "React" which is what we are using. You will only need the text in the curly brackets on the first line.
+4. Next, simply paste `icon: YourIcon` into Frontmatter.
+
+## Callout
+
 You can also make a Callout to highlight important information or tips. Use the following syntax:
 
 ```mdx
@@ -78,6 +110,23 @@ You can change the color of the callout by adding a `type` attribute. For exampl
 ```
 
 Available types are: `info`, `warning`, `error`, and `success`.
+## Difficulty levels
+
+These are types of callouts, they are optional, they show how complex your page can be.
+There are 3 main types of complexity.
+
+<Callout type="lvl_beginner">
+    Use `lvl_beginner`. This page contains information for those who are starting out with modding.
+</Callout>
+<Callout type="lvl_intermediate">
+    Use `lvl_intermediate` This page contains information for those who want to deepen their knowledge.
+</Callout>
+<Callout type="lvl_advanced">
+   Use `lvl_advanced`This page contains information for those who already know how to make quality mods, and contains something additional.
+</Callout>
+
+Their usage is the same as in callout, but we would advise not to change the title. Inside, 
+you write why your page is classified as this type and what the user should know.
 
 ## Conclusion
 

content/docs/en/guides/plugin/creating-commands.mdx

@@ -68,7 +68,7 @@ Unlike `AbstractAsyncCommand` commands using `AbstractPlayerCommand` run on the
 
 You can use the `Store` along with the `Ref` to access all entity components like the `Player` component, `UUIDComponent` or `TransformComponent`.
 
-For more information about Hytale's Entity Component System visit the [Hytale ECS Theory](https://hytalemodding.dev/en/docs/guides/ecs/hytale-ecs-theory) guide.
+For more information about Hytale's Entity Component System visit the [Hytale ECS Theory](../ecs/hytale-ecs-theory) guide.
 
 
 ```java

content/docs/en/index.mdx

@@ -1,6 +1,6 @@
 ---
 title: Introduction
-description: Necessary knowledge for modding Hytale.
+description: Essential knowledge for modding Hytale.
 ---
 
 Hytale is a voxel-based sandbox RPG game by **Hypixel Studios**, as described on the [Hytale website](https://hytale.com/):
@@ -10,10 +10,10 @@ Hytale is a voxel-based sandbox RPG game by **Hypixel Studios**, as described on
 > of dungeons, secrets, and a variety of creatures, then shape it block by block.
 
 Hytale has been built from the ground up with modding and user-generated content in mind.
-The goal of **Hytale Modding** is to provide an excellent resource such that anybody
-is able to mod Hytale for themselves, regardless of skill level or specialization.
+The goal of **Hytale Modding** is to provide an excellent resource so that
+ anyone can mod Hytale themselves, regardless of skill level or specialization.
 
-It is important to note that modding Hytale is not restricted to programming plugins.
-Programming, visual scripting, texturing, 3D modelling, modifying assets, etc. are all modding.
+It is important to note that modding Hytale is not restricted to programming plugins only.
+Programming, visual scripting, texturing, 3D modelling, modifying assets, etc., are all modding.
 
 <u>In Hytale, anyone can be a modder.</u>

content/docs/en/quick-start.mdx

@@ -1,16 +1,35 @@
 ---
 title: Quick Start
-description: Setting up a standard Hytale project.
+description: How to start modding.
+icon: CircleQuestionMark
 ---
 
 Welcome to the Hytale modding documentation! Here you'll find everything you need to know about creating your own mods for Hytale.
 
-- [Java Basics](./guides/java-basics/00-introduction)
-- [Setting up your dev environment](./guides/plugin/setting-up-env)
-- [Entity Component System (ECS)](./guides/ecs/entity-component-system)
-- [Publishing your mod](./publishing)
+<Callout type="info">
+Hytale Modding is primarily documentation, so we don't provide a full modding guide.
+</Callout>
 
-### Useful Links
+## Where to start
+If you don't know anything about modding Hytale or even Java, or you would like to brush up on your knowledge, here are some links that will help you with that.
 
+- [Java Basics](./guides/java-basics/00-introduction) - learn the Java syntax and language features you'll need for modding.
+- [Learning to learn](./guides/learning-to-learn) - why are we using Java.
+- [Setting up your dev environment](./guides/plugin/setting-up-env) - set up your project for development.
+- [Build and test](.guide/plugin/build-and-test) - build your project.
+- [Logging](./guides/plugin/logging) - find and interpret output from your mod when you run the game.
+- [Creating a Block](./guides/plugin/creating-block) - build a simple block to verify your setup works.
+
+If you have experience or you want to try something harder:
+- [World Generation](./guides/plugin/world-gen) - add new terrain, biomes, and custom ore spawns.
+- [Custom Camera Controls](./guides/plugin/customizing-camera-controls) - change how the player camera behaves during gameplay.
+- [Entity Component System (ECS)](./guides/ecs/entity-component-system) - how to use ECS.
+- [Prefabs](./guides/prefabs) - build reusable structures and templates for world editing.
+- [Publishing your mod](./publishing) - package and share your mod with others.
+
+## Guides
+Here are some links to guides that will help you learn how to make mods.
+
+### Video guides
 - [Kaupenjoe's Modding Videos](https://www.youtube.com/@ModdingByKaupenjoe)
 - [TroubleDEV's Modding Videos](https://www.youtube.com/@TroubleDEV)

messages/en.json

@@ -25,6 +25,10 @@
     "hytaleReleased": "Hytale is out!"
   },
 
+  "showcaseItems":{
+    "madeBy": "by {author}"
+  },
+
   "sponsors": {
     "title": "Support Us",
     "description": "HytaleModding is an open-source community project, and part of managing the community involves paying for services, servers and infrastructure, like hosting this website. If you would like to support the project, consider becoming a sponsor! We use OpenCollective so you can see how funds are being used to support the community.",
@@ -89,5 +93,17 @@
     "community_projects": {
       "title": "Community Projects"
     }
+  },
+
+  "callout":{
+      "defaultTitles":{
+        "info": "Info",
+        "warning": "Warning",
+        "danger": "Danger",
+        "success": "Success",
+        "lvl_beginner": "Level: Beginner",
+        "lvl_intermediate":"Level: Intermediate",
+        "lvl_advanced": "Level: Advanced"
+      }
   }
 }

src/app/[lang]/(home)/page.tsx

@@ -58,77 +58,77 @@ interface ShowcaseItem {
 const showcaseItems: ShowcaseItem[] = [
   {
     title: "Hynergy: Electric Motor",
-    author: "by seyager",
+    author: "seyager",
     image: ElectricMotor,
     link: "https://x.com/SeyagerYT",
     type: "art",
   },
   {
     title: "[WIP] Hylamity: Wulfrum Prosthesis",
-    author: "by slader._.",
+    author: "slader._.",
     image: WulfrumProsthesis,
     link: "https://discord.gg/f2fMKYnRqR",
     type: "art",
   },
   {
     title: "[WIP] Soundscape: Melodium Chunk",
-    author: "by 44Hydras",
+    author: "44Hydras",
     image: Melodium,
     link: "https://discord.com/users/197065442479702016",
     type: "art",
   },
   {
     title: "Gale Wivern",
-    author: "by Nicolas | Tourne_Vis",
+    author: "Nicolas | Tourne_Vis",
     image: GaleWivern,
     link: "https://x.com/TourneVis_MC",
     type: "art",
   },
   {
     title: "[WIP] Hylamity: Wulfrum Armor",
-    author: "by slader._.",
+    author: "slader._.",
     image: WulfrumArmor,
     link: "https://discord.gg/f2fMKYnRqR",
     type: "art",
   },
   {
     title: "[WIP] Hylamity: Wulfrum Triangle",
-    author: "by slader._.",
+    author: "slader._.",
     image: WulfrumTriangle,
     link: "https://discord.gg/f2fMKYnRqR",
     type: "art",
   },
   {
     title: "Saqvobase's Spellcasting: Magic Circle - Gust",
-    author: "by Saqvobase",
+    author: "Saqvobase",
     image: MagicCircleGust,
     link: "",
     type: "art",
   },
   {
     title: "Shroomie",
-    author: "by Miyako Hikari",
+    author: "Miyako Hikari",
     image: Shroomie,
     link: "",
     type: "art",
   },
   {
     title: "Froggy",
-    author: "by Unknown Knight",
+    author: "Unknown Knight",
     image: Froggy,
     link: "",
     type: "art",
   },
   {
     title: "Voile",
-    author: "by mayuna",
+    author: "mayuna",
     image: VoileBanner,
     link: "https://www.curseforge.com/hytale/mods/docs",
     type: "art",
   },
   {
     title: "Hylandia",
-    author: "by Kristian / Hylandia Studios",
+    author: "Kristian / Hylandia Studios",
     logo: HylandiaLogo,
     banner: HylandiaBanner,
     link: "https://discord.gg/hylandia",
@@ -142,6 +142,7 @@ const ShowcaseCard = ({ item }: { item: ShowcaseItem }) => {
   const hasImage = item.image;
   const hasLogo = item.logo;
   const hasBanner = item.banner;
+  const messages = useMessages();
 
   return (
     <Card className="relative h-64 w-96 overflow-hidden">
@@ -154,7 +155,7 @@ const ShowcaseCard = ({ item }: { item: ShowcaseItem }) => {
                   {item.title}
                 </h3>
                 <p className="text-muted-foreground z-20 text-base">
-                  {item.author}
+                  {messages.showcaseItems.madeBy.replace("{author}", item.author)}
                 </p>
                 {item.description && (
                   <p className="text-muted-foreground z-20 mt-1 line-clamp-2 text-sm">

src/components/mdx/Callout.tsx

@@ -1,8 +1,11 @@
+"use client";
+
 import { ReactNode } from "react";
-import { Info, AlertTriangle, XCircle, CheckCircle } from "lucide-react";
+import { Info, AlertTriangle, XCircle, CheckCircle, GraduationCap} from "lucide-react";
+import { useMessages } from "@/lib/hooks/useMessages";
 
 interface CalloutProps {
-  type?: "info" | "warning" | "danger" | "success";
+  type?: "info" | "warning" | "danger" | "success"| "lvl_beginner" | "lvl_intermediate" | "lvl_advanced" ;
   title?: string;
   children: ReactNode;
 }
@@ -15,23 +18,34 @@ const styles = {
     "bg-red-50 dark:bg-red-950/50 border-red-200 dark:border-red-800 text-red-900 dark:text-red-100",
   success:
     "bg-green-50 dark:bg-green-950/50 border-green-200 dark:border-green-800 text-green-900 dark:text-green-100",
+    lvl_beginner: "bg-emerald-50 dark:bg-emerald-950/50 border-emerald-300 dark:border-emerald-700 text-emerald-900 dark:text-emerald-100",
+  lvl_intermediate: "bg-amber-50 dark:bg-amber-950/50 border-amber-300 dark:border-amber-700 text-amber-900 dark:text-amber-100",
+  lvl_advanced: "bg-rose-50 dark:bg-rose-950/50 border-rose-300 dark:border-rose-700 text-rose-900 dark:text-rose-100",
 };
 
 const icons = {
   info: Info,
   warning: AlertTriangle,
   danger: XCircle,
   success: CheckCircle,
-};
-
-const defaultTitles = {
-  info: "Info",
-  warning: "Warning",
-  danger: "Danger",
-  success: "Success",
+  lvl_beginner: GraduationCap,
+  lvl_intermediate: GraduationCap,
+  lvl_advanced: GraduationCap
 };
 
 export function Callout({ type = "info", title, children }: CalloutProps) {
+  const messages = useMessages();
+
+  const defaultTitles = {
+    info: messages.callout.defaultTitles.info,
+    warning: messages.callout.defaultTitles.warning,
+    danger: messages.callout.defaultTitles.danger,
+    success: messages.callout.defaultTitles.success,
+    lvl_beginner: messages.callout.defaultTitles.lvl_beginner,
+    lvl_intermediate: messages.callout.defaultTitles.lvl_intermediate,
+    lvl_advanced: messages.callout.defaultTitles.lvl_advanced,
+  };
+
   const Icon = icons[type];
   const displayTitle = title || defaultTitles[type];
 

src/lib/hooks/useMessages.ts

@@ -1,3 +1,5 @@
+"use client";
+
 import { useParams } from "next/navigation";
 import { getMessages, Messages } from "../locale";
 import { deepMerge } from "../utils";