feat: Fleshed-out docs with about section and root README links (#39)

.mise.toml

@@ -30,4 +30,4 @@ run = ["gofmt -s -w .", "goimports -w .", "shfmt -w -i 2 -ci -sr ."]
 
 [tasks.docsdev]
 description = "Run local dev loop for the docs folder"
-run = "cd docs && bun run docs:dev"
+run = "cd docs && bun install && bun run docs:dev"

README.md

@@ -1,11 +1,8 @@
 # stencil
 
-[![go.dev reference](https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&logoColor=white)](https://pkg.go.dev/go.rgst.io/stencil)
+A modern living-template engine for evolving repositories.
 
-A modern repository templating engine
-
-**Note**: This has been forked from [getoutreach/stencil](https://github.com/getoutreach/stencil) and is currently
-under construction.
+Check out our [Documentation](https://stencil.rgst.io/) for more information!
 
 ## Development
 
@@ -52,7 +49,7 @@ Wait for CI to build and publish the release (Github Actions).
 
 ### Building docs
 
-If you have `mise` installed, you should have all the tooling you need for the docs engine. Just run `mise run docsdev` from the root stencil directory to enter the watch-rebuild cycle to test your docs changes.
+If you have `mise` installed, you should have all the tooling you need for the docs engine. Run `mise run docsdev` from the root stencil directory to enter the watch-rebuild cycle to test your docs changes.
 
 ## License
 

docs/about/blocks.md

@@ -0,0 +1,11 @@
+---
+order: 30
+---
+
+# Blocks
+
+The real magic of stencil is that its templates support blocks for extensibility points. As such, any file generated by the template can be a hybrid of user-maintained code and template-driven code. The template owner can evolve all of the code outside of the blocks, allowing their users to extend config, services, and business logic at prescribed points. If a template wants to change how CI or CD works, or change an observability system out from under its users, it's easy to do so just by changing template code. Then when your users re-run the templates, all of their business logic remains intact and they pick up the new templated reusable code that is traditionally considered annoying boilerplate -- your users quickly move into a world of worrying about their business logic and taking the boilerplate for granted.
+
+## Example
+
+For examples of blocks, jump into the middle of our [Guide](/guide/base-project.html#step-4-modifying-a-block) to see them in action.

docs/about/history.md

@@ -0,0 +1,11 @@
+---
+order: 20
+---
+
+# History
+
+Stencil was created by developers at [Outreach](https://www.outreach.io/) in 2020, and originally named `bootstrap`, for obvious reasons -- if you wanted to bootstrap a new project, we wanted to automate that process for our developers. We were just entering an era of monolith decomposition -- starting to build microservices en masse to extract functionality out of the monolith -- and wanted to keep our feature developers from diverging too heavily from each other. We quickly saw that basic templating didn't get us very far -- our users immediately went off the rails to accomplish what they needed since bootstrap was no help after creation. We quickly came up with the idea of _blocks_ to provide an explicit interface for where we wanted users to extend, separating it from code that we wanted to expressly forbid them from changing.
+
+As the project grew and grew, we took our learnings from `bootstrap` and created a new project from scratch called `stencil`, which we intended to be open sourced from day 1, and included a generic module system from the start. This allowed our different tooling teams to build multiple modules of independent templates, and consumers using stencil could independently version those modules as they wanted to update (or roll back if a bad template release happened).
+
+Stencil is now maintained as an open source project, no longer affiliated with Outreach, by some of the original developers of the tool.

docs/about/index.md

@@ -0,0 +1,5 @@
+---
+order: 10
+---
+
+# About

docs/about/native-extensions.md

@@ -0,0 +1,13 @@
+---
+order: 40
+---
+
+# Native Extensions
+
+Another important feature we added to stencil was support for [Native Modules](/reference/native-extensions.md). This allows you to add native code (we've used Golang, but other languages are viable as well since it uses a generic RPC interface for communication) to modules. We've used this for interfacing with other codegen systems like [goverter](https://github.com/jmattheis/goverter), running database migrations and extracting/codegenning data models from finished database schemas, and many other uses for when you need something more complicated than just living templates.
+
+For an example of a basic native extension, check the [Guide](/guide/basic-native-extension) and it will probably be a little clearer.
+
+## Next Steps
+
+So that's the crash course. Does this sound interesting to you? Get started with our [Guide](/guide/installation)!

docs/about/problem-statement.md

@@ -0,0 +1,12 @@
+---
+order: 10
+---
+
+# Problem Statement
+
+Stencil is a bit of a new paradigm in repository lifecycle management -- it's not just a templating engine, its intention is to use _living templates_. Existing templating tools are great at the conception of a project, allowing you to safely start from a known-good template to start your codebase and build out from there. However, as time moves on, two things tend to happen:
+
+1. There are updates in the code from whoever built out the template in the first place (often a dedicated tooling team at larger companies).
+2. The project using the template grows up and wants to add more (possibly-templated) functionality, but they didn't select the options at the time they built their project, so they usually end up making a new project with the right options and trying to shoehorn the new code into their existing project.
+
+Both of these problems are solved by stencil, which evolve the thinking towards living templates that help all your projects evolve over time together. At larger companies, where you might be building dozens or even hundreds of microservices, having a single resilient and reliable base to build all of your services off is hugely helpful to save your developers time. It's even more helpful when that resilient base evolves regularly with patches, functionality, observability, and more. As template owners grow their templates and support more features, your users can immediately pick up those features, often times doing so in a completely automated fashion -- apply the latest stencil templates, have the PR run unit tests, and auto-merge if everything passes.

docs/functions/index.md

@@ -1,5 +1,5 @@
 ---
-order: 3
+order: 40
 ---
 
 # Functions

docs/guide/index.md

@@ -1 +1,5 @@
-# Guide
+---
+order: 20
+---
+
+# Guide

docs/index.md

@@ -6,11 +6,11 @@ title: Home
 hero:
   name: stencil
   tagline: |
-      Modern repository templating engine
+    A modern living-template engine for evolving repositories
   actions:
     - theme: brand
       text: About
-      link: /about
+      link: /about/problem-statement.html
     - theme: alt
       text: Guide
       link: /guide/installation.html
@@ -19,9 +19,8 @@ hero:
       link: https://github.com/rgst-io/stencil
 
 features:
-  - title: <a href="/guide/installation.html">Development Lifecycle Management</a>
+  - title: <a href="/about">Development Lifecycle Management</a>
     details: stencil goes further than other templating tools by defining extensibility "blocks" to explicitly separate what your consumers can and can't extend, encouraging a system of regularly re-running stencil to pull in living-and-progressing templates.
-  - title: <a href="/native-extensions.html">Native Extensions</a>
+  - title: <a href="/reference/native-extensions.html">Native Extensions</a>
     details: Need to interface with an API or implement custom parsing/merging logic? Stencil supports native extensions in _any_ language to implement that logic.
-
 ---

docs/reference/index.md

@@ -1 +1,5 @@
+---
+order: 30
+---
+
 # Reference