Creating Guides

Hey! Before starting, let’s stand this guide is just for the one wondering to contribute with KAPLAY Docs, specifically the guides part. Thanks for your interest on improving KAPLAY ♥

Get the repo

git clone https://github.com/kaplayjs/kaplay-site.git
pnpm i
pnpm dev

Then, when you finish, just Open a PR.

Guidelines

Communication

The most important thing for creating a guide is the communication with KAPLAY Dev internals, you can use the #dev channel, telling us what guide are you updating (so no other dev interfers with that) or any other question/blocker you got.

Creating your guide

After cloning the repo, go to /guides/en/ and create in any of the category folders an .mdx file, for example /guides/en/concepts/anchor.mdx.

This is the frontmatter used in all guides:

---
title: Creating Guides # The title, it appears in the sidebar
description: You shouldn't see this # Description for metadata
version: "4000" # Don't use it unless the guide is only for v4000
url: contributor-guide-on-guides # The url
order: "misc-4" # The order string, just follow the others in the same category
hidden: true # Hide it
noads: true # Disable ads (used in Contributors pages)
---

You can know available categories just looking the folders inside /guides/ or /guides/data.json.

Writing style

There’s little things you’ve to take in account in the writing style

• Main Title should be the same than frontmatter title.
• Talk to the user as you. Instead of “we can use get() for…” do “you can use get()” for
• Try to do descriptive titles, instead of Introduction -> How to X / Creating X

”X Operations” or “How To” collection sections

Some guides include many How to section under a “X Operations” section, as a complement of main content, check for example Game Object guide, we could standarize this format:

## [Title of Guide] Operations 

### How to [thing]

You can do [thing] with [thing they can use]

Components and features in Markdown

There’s some special components and Markdown features you must know for creating a great quality document piece.

Info component

Display useful information or tips.

Usage

import Info from "@/components/Content/Info.astro";

<Info crew="mark" title="oh!">
Say hi!
</Info>

Props

Rendered

There’s many cool usages of this component among guides.

JustForVersion component

Display useful information or tips.

Usage

import JustForVersion from "@/components/Content/JustForVersion.astro";

<JustForVersion version="4000">
## This Markdown

Is just rendered in the 4000 version.
</JustForVersion>

Props

Rendered

Code component

Render JavaScript code with an option to Open in KAPLAYGROUND. Don’t worry by formatting, it auto formats.

Usage

import Code from "@/components/Content/CodeWithKAPLAYGROUND.astro";

<Code
    code={`
// Code to be rendered
    `}
    pgCode={`
// Code to be played
    `}
/>

Props

Rendered

API Docs links

You can easily link to API Docs writing an entry name them between backticks (`):

You can use `get(*)` for getting all objects. There's also `GameObjRaw.get()`. 
It doesn't matter the content between (), it will be ignored for generating the link.

Rendered

Special aliases for API Docs links

You can use convenient alias like obj for refer to GameObjRaw, there’s the table with all special aliases and features around this: