docs: getting started

README.md

@@ -12,7 +12,7 @@
 
 ## Introduction
 
-Minecraft [resource packs](https://minecraft.gamepedia.com/Resource_Pack) and [data packs](https://minecraft.gamepedia.com/Data_Pack) work well as _distribution_ formats but can be pretty limiting as _authoring_ formats. You can quickly end up having to manage hundreds of files, some of which might be buried within the bundled output of various generators.
+Minecraft [resource packs](https://minecraft.wiki/w/Resource_pack) and [data packs](https://minecraft.wiki/w/Data_pack) work well as _distribution_ formats but can be pretty limiting as _authoring_ formats. You can quickly end up having to manage hundreds of files, some of which might be buried within the bundled output of various generators.
 
 The `beet` project is a development kit that tries to unify data pack and resource pack tooling into a single pipeline. The community is always coming up with pre-processors, frameworks, and generators of all kinds to make the developer experience more ergonomic. With `beet` you can seamlessly integrate all these tools in your project.
 

docs/getting_started/index.md

@@ -0,0 +1,56 @@
+# Getting Started
+```{toctree}
+:hidden:
+
+plugins
+```
+Beet is a development toolkit for working with Minecraft data and resource packs. This section will explain how to install beet and get started with a first project.
+
+## Installation
+To start, you will need [Python 3.10+](https://python.org/). Then, you can install beet via pip. This will give you access to the CLI command that you can use inside your terminal.
+```bash
+pip install beet
+```
+
+## Creating a project
+Beet projects start with a configuration file, `beet.json`, in the root of your project.
+
+```{tab} beet.json
+```json
+{
+  "name": "My First Pack",
+  "description": "Learning beet!",
+
+  "data_pack": {
+    "load": ["src"]
+  },
+
+  "output": "build"
+}
+```
+
+This beet config describes a basic data pack which has a name, description, where to load in the data pack, and finally, where the output pack will be produced. To test it out, you can create a data pack function inside the `src` folder.
+
+```{tab} src/data/example/function/hello.mcfunction
+```mcfunction
+say hello beet
+```
+
+## Building the pack
+Now, navigating back to the root directory, you can invoke the build process and your pack will build, check it out in the output directory!
+```bash
+beet build
+```
+
+Alternatively, beet can watch the source files and automatically build the pack when it detects changes:
+```bash
+beet watch
+```
+
+## Linking to a world
+It is possible to automatically link the output pack to a world in your saves folder.
+```bash
+beet build --link "My World"
+```
+
+This will automatically look for the minecraft folder. If you are using a third party launcher, you can override this with the `MINECRAFT_PATH` environment variable.

docs/getting_started/plugins.md

@@ -0,0 +1,39 @@
+# Plugins
+A beet plugin is essentially a Python function that takes the build context as an argument.
+
+```{tab} my_plugins.py
+```py
+from beet import Context, Function
+
+def add_greeting(ctx: Context):
+  ctx.data["example:hello"] = Function(["say hello from a plugin"])
+```
+
+The `Context` object lets you access the data pack with the `data` attribute. Similarly, you are able to get the resource pack with the `assets` attribute.
+
+Just adding this file won't change anything. That's because plugins need to be used inside the beet pipeline in the config:
+
+```{tab} beet.json
+```json
+{
+  "data_pack": {
+    "load": ["src"]
+  },
+  "pipeline": [
+    "my_plugins.add_greeting"
+  ],
+  "output": "build"
+}
+```
+
+## Modifying existing files
+Plugins can introspect and modify any part of the build. For example, the following plugin prepends every function with its name:
+
+```{tab} my_plugins.py
+```py
+from beet import Context, Function
+
+def function_headers(ctx: Context):
+  for name, func in ctx.data.functions.items():
+    func.lines.insert(0, f"# {name}")
+```

docs/index.md

@@ -14,7 +14,9 @@ You can follow the development of the project, discuss ideas, get help, and hang
 
 ```{toctree}
 :hidden:
+:maxdepth: 2
 
+getting_started/index
 rationale
 overview
 changelog
@@ -26,6 +28,7 @@ changelog
 
 GitHub Repository <https://github.com/mcbeet/beet>
 PyPI Package <https://pypi.org/project/beet>
+Beet Discord <https://discord.gg/98MdSGMm8j>
 ```
 
 ```{include} ../README.md