Creating Guides

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

Get the repo

git clone https://github.com/buildnana/buildnana-site.git
git submodule init
git submodule update
pnpm ci
pnpm dev

Then, when you finish, just Open a PR.

Guidelines

Communication

The most important thing for creating a guide is communication. You can open a GitHub issue or start a discussion, telling us what guide you are updating (so no other dev interferes with that) or any other question/blocker you have.

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

Prop	Description
`crew`: `string`	Crew member to display
`title`: `string`	Title to display, it supports MarkDown

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

Prop	Description
`version`: `string`	The version to display
`requireToBeEqualIn`: `"major", "minor" or "patch"`	The level of numbers the component will check for conditionally rendering, being just major in `major`, major and minor in `minor` and the three numbers in `patch`.

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

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

Props

Prop	Description
`code`: `string`	The JavaScript code to be rendered.
`pgCode?`: `string`	The JavaScript code to be played in BUILDNANAGROUND, if there’s not, `code` is used
`addBUILDNANACall?`: `boolean`	If no `pgCode`, it will use `code` inserting `buildnana()` in the start
`loadCrew`: `string[]`	Load sprites from crew in the start of the example. Just works if `addBUILDNANACall` is true, and just work with sprites for now.

Rendered

// Code to be 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

You can use get() for getting all objects. There’s also GameObjRaw.get().

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:

This	Refers to	Works in
obj	`GameObjRaw`	Referring to `GameObjRaw` members. `obj.id` links to `GameObjRaw.id`
debug	`Debug`	Referring to `Debug` members. `debug.log()` links to `Debug.log()`
obj.[componentMethod]	That component	Referring to component members as they were part of `obj`. `obj.onDoubleJump()` links to `DoubleJumpComp.onDoubleJump()`

Installation