Rewrite the old documentation

docs/filters/installing-filters.md → docs/filters/filter-installation.md

@@ -1,4 +1,4 @@
-(installing-filters)=
+(filter-installation)=
 # Installing and Updating Filters
 
 To start using a filter, you need to do four things:

docs/filters/filters.md → docs/filters/filters-introduction.md

@@ -1,3 +1,4 @@
+(filters-introduction)=
 # Filters Introduction
 
 A filter is any program or script that takes the files inside of your RP and BP and *transforms* them in some way. Many of these filters have already been written, and are included as part of the {ref}`standard library<standard-library>`. You may also be interested in {ref}`community filters<community-filters>`

docs/index.md

@@ -2,8 +2,8 @@
 :hidden:
 :caption: Introduction
 
-What Is Regolith? <introduction/what-is-regolith>
-Installing <introduction/installing>
+Introduction <introduction/introduction>
+Installation <introduction/installation>
 Getting Started <introduction/getting-started>
 Troubleshooting <introduction/troubleshooting>
 ```
@@ -25,11 +25,11 @@ Safety <advanced/safety>
 :hidden:
 :caption: Filters
 
-Introduction <filters/filters>
+Filters Introduction <filters/filters-introduction>
 Local Filters <filters/local-filters>
 Custom Filters <filters/custom-filters>
 Online Filters <filters/online-filters>
-Installing Filters <filters/installing-filters>
+Filter Installation <filters/filter-installation>
 Filter Run Modes <filters/filter-run-modes>
 Create a Filter <filters/create-a-filter>
 ```

docs/introduction/getting-started.md

@@ -1,7 +1,7 @@
 # Getting Started
 
 ```{note}
-To get started with Regolith, you should first read our {ref}`introduction<what-is-regolith>` page, and the {ref}`installation<installing>` page.
+To get started with Regolith, you should first read our {ref}`introduction<introduction>` page, and the {ref}`installation<installation>` page.
 ```
 
 You can test for installation by running `regolith` inside of a terminal. This guide will assume you have installed regolith directly, but you can follow along with a stand-alone build. Just ensure that the executable is placed inside of your project folder.
@@ -142,4 +142,4 @@ Now that you've created your first Regolith project, and installed your first fi
 
 Otherwise, you can learn about writing {ref}`custom filters<custom-filters>` or
 dive deeper into Regolith commands by reading about {ref}`Filter Run Modes<filter-run-modes>`
-and {ref}`Installing and Updating Filters<installing-filters>`.
+and {ref}`Installing and Updating Filters<filter-installation>`.

docs/introduction/installation.md

@@ -0,0 +1,64 @@
+(installation)=
+# Installation
+You can install Regolith using various methods, depending on your operating system. This section provides instructions for installing Regolith on Linux, Mac, and Windows systems.
+
+## Winget (Windows)
+To install Regolith using winget, open a command prompt or terminal window and enter the following command:
+```
+winget install Bedrock-OSS.regolith
+```
+This will search the winget repository for the "Bedrock-OSS.regolith" package and install it on your system. If the installation is successful, you should see a message indicating that the package has been installed.
+
+To update Regolith in the future, simply run the following command:
+```
+winget upgrade Bedrock-OSS.regolith
+```
+This will check for any available updates to the Regolith package and install them on your system.
+
+```{warning}
+Not every Windows computer has winget installed. If this is the case for your computer, you can install Regolith using the MSI file available on GitHub (see next section for instructions).
+```
+
+## MSI File (Windows)
+
+You can install Regolith using the MSI file available on the release page on GitHub: [https://github.com/Bedrock-OSS/regolith/releases/latest](https://github.com/Bedrock-OSS/regolith/releases/latest)
+
+
+![](./installation/msi-download.png)
+
+The MSI file name follows the pattern `regolith-x.x.x.msi`, where `x.x.x` is the version number. Simply download the MSI file from the link above and run it to begin the installation process. Follow the prompts to complete the installation.
+
+![](./installation/regolith-msi.png)
+
+## Updating (Windows)
+
+To update Regolith after installation, you can use the "regolith-update.ps1" PowerShell script that is included with the installation. To run the script, follow these steps:
+
+1. Open a PowerShell window.
+2. Run the following command:
+
+```
+regolith-update.ps1
+```
+
+This will check for any available updates to Regolith and install them on your system.
+
+## Stand-alone Executable File (Linux, Mac, and Windows)
+
+Regolith can also be installed stand-alone. Simply download the correct zip for your operating system from the release page on GitHub: [https://github.com/Bedrock-OSS/regolith/releases/latest](https://github.com/Bedrock-OSS/regolith/releases/latest)
+
+For Windows, this is most likely `regolith_x.x.x_Windows_x86_64.zip`.
+
+![](./installation/exe-download.png)
+
+Unzip this package, and place the Regolith executable file somewhere convenient. In stand-alone mode, you will need a add the executable to your PATH environment variable or copy it into every project.
+
+## Checking Installation
+
+After installing, Regolith can be used in command-prompt by typing `regolith`. You should see something like this:
+
+![](./installation/regolith-help.png)
+
+```{note}
+If you don't see this try restarting your terminal.
+```

docs/introduction/introduction.md

@@ -0,0 +1,76 @@
+(introduction)=
+# Introduction
+
+## What is Regolith?
+
+Regolith is a pack compiler for the Bedrock Edition of Minecraft.
+
+Regolith introduces the concept of a **project folder**, that includes the resource pack, behavior pack, and data folder that can be used for additional configuration. This structure is great for version control, and allows you to keep your "source-of-truth" outside of Minecraft's `com.mojang` folder.
+
+Here is what a newly initialized Regolith project looks like:
+
+```text
+📂 example-project
+    📂 .regolith
+    📂 packs
+        📂 BP
+        📂 data
+        📂 RP
+    📄 .gitignore
+    📄 config.json
+```
+
+### Compilation Flow
+
+In the simplest case, Regolith can be used to move your packs from the project folder, into your target location (usually the development folders in `com.mojang`). Each time you run regolith, the packs will be moved over, and updated.
+
+However, Regolith's real value preposition is the ability to run {ref}`arbitrary code during this copy<safety>`.
+
+We refer to these scripts and programs as {ref}`filters<filters-introduction>`. Here is the flow:
+1. `RP`, `BP` and `data` folder are copied into a temporary location.
+2. Every filter is executed in-order, editing temporary files in-place.
+3. The contents of `RP` and `BP` are moved into your export location
+4. If configured, some of the subfolders within `data` can be moved back into your data location
+
+This compilation flow allows you to make programmatic changes to your compiled addon, without effecting your source files. Since the data folder can be saved back to your project, it's possible to persistantly store the results of running filters there.
+
+## Why Regolith?
+
+### Extending the Addon Syntax
+
+Regolith allows you to create and extend addon-syntax. For example, the [subfunctions](https://github.com/Nusiq/regolith-filters/tree/master/subfunctions) community filter allows you to define functions within functions, without creating an additional file:
+
+```
+# Some code
+function <aaa>:
+    # The code of the subfunction
+    execute @a ~ ~ ~ function <bbb>:
+        # The code of the nested subfunction
+# Some other code
+```
+
+Regolith's capablities go beyond chaning the individual files. You can change entire structure of the project and use files that otherwise would not be supported by Minecraft (for example, custom image formats).
+
+As long as you can write a filter to interpret the new structure, and compile it into valid pack, then anything goes!
+
+### Non-Destructive Editing
+
+Imagine you have a script that loops over every entity, and creates some language-code translation for it.
+
+Lets say your entity `regolith:big_zombie` becomes named `Big Zombie`.
+
+If you run this script, and copy the files into your `en_US.lang`, you've saved yourself a lot of time, but you've also introduced a problem: You've *destructively edited your pack*. What this means, is that you have mixed up your tool-generated content, with your hand-written content.
+
+Imagine you add more entities, and run your script again: Now you are in the painful position of "merging" the new tool generated content, with your resource pack's `en_US.lang` file, which you may have edited in the interim.
+
+This is called *destructive editing*, and Regolith fixes it!
+
+A comparable Regolith filter would not suffer from this problem, because you never directly edit tool generated content. Your Regolith project folder contains only human written content, and your `com.mojang` folder contains only tool-generated content.
+
+This means as you add new entities, the names will be handled for you, without you ever seeing the names in `en_US.lang`, or needing to re-run the script!
+
+In other words, Regolith adds compiled content on top of your hand written content, leaving you free to create your content, without working around tool-generated content.
+
+```{note}
+If this sounds interesting to you, you might be interested in the [name ninja filter](https://github.com/Bedrock-OSS/regolith-filters/tree/master/name_ninja).
+```