better docs

README.md

@@ -15,9 +15,9 @@
 
 </div>
 
-blueprint is an opinionated library that maps a standard folder structure to
-flake outputs. It makes common use cases easy both for the author and
-consumers.
+blueprint is an opinionated library that maps a standard folder structure to flake outputs, allowing you to divide up your flake into individual files across these folders. This allows you to modularize and isolate these files so that they can be maintained individually and even shared across multiple projects. 
+
+Blueprint also  makes common use cases easy for both the author and consumers.
 
 Eg:
 
@@ -44,28 +44,15 @@ Support for:
 
 and more!
 
-## Documentation
-
-* [Getting started](docs/getting-started.md)
-* [Configuring blueprint](docs/configuration.md)
-* [Folder structure mapping](docs/folder-structure.md)
-
 ## Rationale
 
-Nix is just a tool. It should help you, and stay out of the way. But because
-it's so flexible, everybody goes through a long period where they figure out
-how to structure their repo. `flake.nix` files become noisy with boilerplate.
+Nix is just a tool. It should help you, and stay out of the way. But because it's so flexible, everybody goes through a long period where they figure out how to structure their repo. `flake.nix` files become noisy with boilerplate.
 
-By making a few opinionated choices, we're able to cut 99% of the glue code
-you would find in most repos. A bit like Ruby on Rails or NextJS did for web
-frameworks, we do it for Nix packages. We map folder and files to flake
-outputs.
+By making a few opinionated choices, we're able to cut 99% of the glue code you would find in most repos. A bit like Ruby on Rails or NextJS did for web frameworks, we do it for Nix packages. We map folder and files to flake outputs.
 
-In some ways, this is the spiritual successor to `flake-utils`, my first
-attempt at making flakes easier to use.
+In some ways, this is the spiritual successor to `flake-utils`, my first attempt at making flakes easier to use.
 
-Blueprint isn't suitable for complex flakes but it does allow you to easily
-break out once your project becomes complicated beyond its capability.
+Blueprint isn't suitable for complex flakes but it does allow you to easily break out once your project becomes complicated beyond its capability.
 
 ## Design principles
 
@@ -80,3 +67,101 @@ break out once your project becomes complicated beyond its capability.
 * [std](https://github.com/divnix/std)
 * [snowflake-lib](https://github.com/snowfallorg/lib)
 * [clan-core](https://git.clan.lol/clan/clan-core) is an all-in-one solution to manage your deployments.
+
+## Full Documentation
+
+You can find the [full documentation here](https://numtide.github.io/blueprint/main/).
+
+## Quickstart
+
+Meanwhile, if you're ready to get started right away, here's what you do.
+
+1. [Install Nix](https://nix.dev/install-nix) or use NixOS.
+2. Run `mkdir my-project && cd my-project`
+3. Run `nix flake init -t github:numtide/blueprint`
+
+Now you're ready to create some folders and special files. The full documentation shows you all the folders and special files available, but for now let's create a couple of development shells, and a formatter. 
+
+Remember, the goal is to divide up the flake.nix file into individual modular parts. This not only helps keep your flake.nix file size down, it lets you create reusable modules that you can easily drop into other projects.
+
+Let's create a package the builds a docker container from our source, assuming your source lives in a folder called src off the root folder. Assume your src entry point is a file called hello.py; in this example, just put the following in `hello.py`:
+
+```
+print('Hello from docker!')
+```
+
+Also from the root folder create a folder called `packages`, and under that a folder called `docker-python-hello`. Inside that folder create a file called `default.nix`, and place the following in it:
+
+```nix
+{ pkgs, system, ... }:
+
+let
+  python = pkgs.python3;
+
+  pythonApp = pkgs.stdenv.mkDerivation {
+    pname = "my-python-app";
+    version = "1.0";
+    src = ../../src;
+
+    installPhase = ''
+      mkdir -p $out/app
+      cp hello.py $out/app/
+    '';
+  };
+
+  rootImage = pkgs.buildEnv {
+    name = "my-docker-root";
+    paths = [ python pythonApp ];
+    pathsToLink = [ "/bin" "/app" ];  # python will be linked in /bin
+  };
+in
+pkgs.dockerTools.buildImage {
+  name = "my-python-hello";
+  tag = "latest";
+
+  fromImage = pkgs.dockerTools.pullImage {
+    imageName = "python";
+    finalImageTag = "3.11-slim";
+    imageDigest = "sha256:7029b00486ac40bed03e36775b864d3f3d39dcbdf19cd45e6a52d541e6c178f0";
+    sha256 = "sha256-lUrhG5Omgdk81NmQwQTo4wnEfq2+r2nGePpgTSYgVU0=";
+  };
+
+  copyToRoot = rootImage;
+
+  config = {
+    WorkingDir = "/app";
+    Cmd = [ "python" "/app/hello.py" ];  # will now work since python is in /bin
+  };
+}
+```
+
+This will build an image into a folder called results; to do so, type the following:
+
+```
+nix build .#docker-python-hello
+```
+
+Note that the name to use must match the name of the folder under the packages folder.
+
+Also notice that nix is able to find the default.nix file thanks to Blueprint. You can then load the image and run it by typing:
+
+```
+docker load < result
+docker run --rm my-python-hello:latest
+```
+
+This should print the message:
+
+```
+Hello from docker!
+```
+
+Note that result is really a symbolic link to a tar.gz file containing the image in the store.
+
+You can view your image by typing the usual:
+
+```
+docker images
+```
+
+

docs/content/getting-started/.pages

@@ -0,0 +1,5 @@
+nav:
+  - install.md
+  - folder_structure.md
+  - built_in_templates.md
+  - configuration.md

docs/content/getting-started/built_in_templates.md

@@ -0,0 +1,59 @@
+# Using Templates
+
+Blueprint comes with several templates to help you get started with your project.
+
+> Note: Feel free to contribute new templates!
+
+To install from a template, use the following format; for example, to use the template called system manager, type:
+
+```
+nix flake init -t github:numtide/blueprint#system-manager
+```
+
+where we appended a hash symbol followed by the template name.
+
+## Default Template
+
+Init command:
+
+```bash
+nix flake init -t github:numtide/blueprint
+```
+
+This is a bare-bones project as described in [install](./install.md).
+
+## NixOS and Darwin Shared Homes Template
+
+```
+nix flake init -t github:numtide/blueprint#nixos-and-darwin-shared-homes
+```
+
+This template is a bit of an example plus a template. You'll want to study all the files carefully. It shows how you can define and reuse modules, in this case nixos and home-manager.
+
+Look carefully at the folder structure; in this case we're using `hosts` and `modules` folders which are both picked up by Blueprint.
+
+If you drill down into the folders, you'll see inside the `hosts` folder, are a `my-darwin` folder and a `my-nixos` folder, both of which are imported by Blueprint. This defines the two hosts called `my-darwin` and `my-nixos`.
+
+Their respective configuration files both import a shared  `modules/nixos/host-shared.nix` module between them.
+
+Also, both hosts define a `me` user and their home-manager configuration simply imports `modules/homes/home-shared.nix`.
+
+Finally, notice in the root `flake.nix` we're adding the home-manager and nix-darwin inputs, which serve as dependencies for managing home configurations and macOS integrations, respectively.
+
+The idea with this template is that you can use this example to get started on how to share configurations between different system and home environments on different hosts.
+
+
+## Toml-DevEnvs
+
+Members of your team might be intimidated by Nix and flake files, and prefer a more traditional method of configuring their devshells. As such, we provide full support for TOML files.
+
+For more information, please visit our [devshell repo](https://github.com/numtide/devshell), which is what powers this template behind-the-scenes.
+
+## System Manager Template
+
+```
+nix flake init -t github:numtide/blueprint#system-manager
+```
+
+Notice that the root flake.nix file we're adding the system-manager input, which is our own project. You can find it on GitHub at [system-manager](https://github.com/numtide/system-manager), where you can read more information on how to use it.
+

docs/content/reference/configuration.md → docs/content/getting-started/configuration.md

@@ -1,24 +1,38 @@
 # Configuration
 
-The flake.nix file offers a few configuration options:
+In this section we describe the blueprint configuration options:
 
 * **prefix**: This lets you specify a directory to hold the folders other than the flake.nix location.
 * **systems**: Defines which systems the project should be used and deployed on.
-* **nixpkgs.config**: If set, Blueprint will create a new instance of nixpkgs for each systems.
-* **nixpkgs.overlays**: If set, blueprint will create a new instance of nixpkgs for each systems.
+* **nixpkgs.config**: If set, Blueprint will create a new instance of nixpkgs for each system.
+* **nixpkgs.overlays**: If set, blueprint will create a new instance of nixpkgs for each system.
 
-Below we provide more detail on each, along with examples.
+These are available by changing the `flake.nix` output invocation with additional parameters.
 
-[TODO: More detail and each; meanwhile I've copied in the current configuration.md file]
+Below we provide more detail on each, along with examples.
 
 ## prefix
 
-Set this if you want to load the blueprint from a directory within the repositiry other than the flake location.
+Set this if you want to load the blueprint from a directory within the repository other than the flake location.
 
 Default: "."
 
 Type: string.
 
+For example, add the following prefix line to your output invocation:
+
+```nix
+outputs = inputs:
+  inputs.blueprint {
+    inherit inputs;
+    prefix = "nix/";
+  };
+```
+
+Then, you can add a `nix` folder inside the same folder that holds your flake file, and place all your folders within this `nix` folder.
+
+> **Tip:** Although you can choose any folder you like, we recommend the name "nix" for your folder, as this is becoming the defacto standard.
+
 ## systems
 
 Defines for which systems the project should be used and deployed on.
@@ -40,13 +54,13 @@ Example:
 
 ## nixpkgs.config
 
-If set, blueprint will create a new instance of nixpkgs for each systems, with the passed config.
+If set, blueprint will create a new instance of nixpkgs for each system, with the passed config.
 
 Default: `inputs.nixpkgs.legacyPackages.<system>`.
 
 Type: attrset.
 
-Example:
+For example, the following sets the allowUnfree attribute of nixpkgs.config to true:
 
 ```nix
 {
@@ -61,13 +75,11 @@ Example:
 
 > NOTE: It's better to use `perSystem` composition style instead of overlays if you can.
 
-If set, blueprint will create a new instance of nixpkgs for each systems, with the passed config.
-
-Default: `inputs.nixpkgs.legacyPackages.<system>`.
+If set, blueprint will create a new overlay with the passed config.
 
 Type: list of functions.
 
-Example:
+Here's an example that creates a couple of overlays; the first ("otherflake") reuses an overlay defined in another flake, and the second, an inline overlay, defines an overlay that replaces the default git package with the smaller gitMinimal:
 
 ```nix
 {