Created a file about templates, created several starter files, added …

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 [getting started](../getting-started/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
 {
@@ -59,9 +73,11 @@ Example:
 
 ## nixpkgs.overlays
 
+[TODO - Rework this part, as currently it's (almost) a copy of nixpkgs.config]
+
 > 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.
+If set, blueprint will create a new instance of nixpkgs for each system, with the passed config.
 
 Default: `inputs.nixpkgs.legacyPackages.<system>`.
 

docs/content/getting-started/install.md

@@ -7,13 +7,13 @@
 
 Let's create a small project with Nix, and you'll see how to add Blueprint to your project.
 
-1. Install [Nix](https://nix.dev/install-nix).
+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`.
 
-Note: After you install Nix, you'll need to enable "experimental features." Find out how here.
+Note: After you install Nix, you'll need to enable "experimental features." Find out how here. [TODO: Let's write a blog post on how to enable experimental features on the different platforms. Googling doesn't bring up high-quality explanations.]
 
-This will give you a barebone project structure with a single `flake.nix` file and a single `devshell.nix` file. (It also provides a basic .envrc, which [TODO] and a starter .gitignore file. Make sure you're aware of this .gitignore file before you accidentally overwrite it.)
+This will give you a barebone project structure with a single `flake.nix` file and a single `devshell.nix` file. (It also provides a basic .envrc, which lets you configure direnv [TODO: Move our direnv document to a blog post] and a starter .gitignore file. Make sure you're aware of this .gitignore file before you accidentally overwrite it.)
 
 Normally, without Blueprint, you would typically include a devShell section inside your flake.nix file. In that scenario, when you want to start a new project with a similar toolset, you'll likely need to copy over the devShell section of your flake.nix file to the new project's flake.nix file. But by using Blueprint, we've split out the devShell into its own file, allowing you to simply copy the file over.
 
@@ -60,7 +60,7 @@ When you run a nix command (such as `nix develop`), this flake.nix file is evalu
 * The devShell.nix file in the root of your project
 * A folder structure
 
-You create the folder structure based on the available list of folders (found here).
+You create the folder structure based on the available list of folders [found here](folder_structure.md).
 
 # A Sample Environment
 
@@ -69,6 +69,8 @@ Let's set up a development environment that includes:
 * Python
 * Python's numpy package
 
+> **Tip:** In this section we'll be creating a default developer environment. You can also set up multiple developer environments and place them in the devshell folder as shown in the devshell section [here](folder_structure.md).
+
 Open up the devshell.nix file in your favorite editor, and update it to look like this:
 
 ```nix
@@ -138,23 +140,113 @@ Check out:
 * Guides
 * Contributing
 
-# (Optional) Configuring direnv
+# Adding folders
 
-Included in the initial files created by Blueprint is a filed called .envrc. This file contains code to configure direnv, which allows you to enter a devshell simply by switching to the folder containing your project. That means you don't need to type `nix develop` after entering the folder. Then when you move up and out of the folder, you'll automatically exit the environment.
+Next, we'll add some folders into your project to give you an idea of how the
+folder system works.
 
-For more information on configuring this feature, check out our guide at [Configuring Direnv](../guides/configuring_direnv.md)
+> **Tip:** It's often good practice to put the folder structure inside its own root folder. That way the folders will be grouped together and easy to distinguish from other folders. As an example, look at [NumTide treefmt](https://github.com/numtide/treefmt). 
+
+Let's start with a root folder to hold the other folders. We'll use "nix" as that's the standard one we've created. Open up your root flake.nix file and expand the outputs line so it takes up multiple lines, and then add in the following prefix attribute:
+
+```nix
+  outputs = inputs:
+    inputs.blueprint {
+      inherit inputs;
+      prefix = "nix/";
+    };
+```
 
+Now create a `nix` folder at the root of your project alongside the flake.nix and devshell.nix files.
 
-## Creating a root folder
+Now you're ready to create some folders.
 
+First, remember that folders are detected automatically by Blueprint. That way, you can drop in place pre-built packages. For example, on another project, you might have built a package that configures mysql. In that project you placed it in a folder called packages. You can then simply create a folder in your new project also called packages, and drop the mysql file in there, and you're good to go. No messing around with giant monolithic flake.nix file.
 
+Let's do something similar. Let's add some documentation to your app. Suppose we want to set up MkDocs with your project.
 
+> **Tip:** Remember, the whole point of Nix is to be able to set up reproducible environments. What that means is you don't need to install MkDocs globally. Instead, you can configure it directly in your project.
 
+1. Under the `nix` folder, create another folder called `packages` (all lowercase).
+2. Then under `packages` create a folder called `docs`.
+3. Inside the `docs` folder, paste the following code into a file called `default.nix`:
 
-## Adding a host
+```nix
+{
+  pkgs,
+  perSystem,
+  ...
+}:
+pkgs.stdenvNoCC.mkDerivation {
+  name = "docs";
+
+  unpackPhase = ''
+    cp ${../../../mkdocs.yml} mkdocs.yaml
+    cp -r ${../../../docs} docs
+  '';
 
-TODO
+  nativeBuildInputs = with pkgs.python3Packages; [
+    mike
+    mkdocs
+    mkdocs-material
+    mkdocs-awesome-nav
+  ];
+
+  buildPhase = ''
+    mkdocs build
+  '';
+
+  installPhase = ''
+    mv site $out
+  '';
+}
+```
+
+> **Tip:** Because Blueprint is present, this code will get loaded automatically as needed. And notice how it can be reused; indeed for this example, we simply copied it over from the [Blueprint project itself](https://github.com/numtide/blueprint/blob/main/packages/docs/default.nix).
+
+This code defines a derivation that builds the documentation. Before you can use it, however, you'll need some documentation. So again off the root folder of your project, create a folder called `docs`. This is where you'll put the documentation.
+
+Inside the `docs` folder, create file called `index.md` and paste in perhaps the following:
+
+```md
+# Welcome to my amazing app!
+We've built this amazing app and hope you enjoy it!
+```
 
-## Adding a package
+Next, we need a file that configures MkDocs called mkdocs.yml. In the root folder, create the file `mkdocs.yml` and paste the following in it:
 
-TODO
+```
+site_name: AwesomeProject
+```
+
+Now let's build the docs using the mkdocs app. We'll build a static site. From your root folder, type:
+
+```
+nix build .#docs
+```
+
+You'll see a `results` folder appear. This contains the output from the mkdocs, which is the built website.
+If you want to run the built-in mkdocs server to try out your site, type:
+
+```
+nix develop .#docs
+```
+
+Notice by calling nix develop, we're entering a development shell. But that happens only after we run the derivation. The derivation will compile our documents into a static site again (if necessary) and make the mkdocs command available to us while in the shell.
+
+Open up a browser and head to `http://127.0.0.1:8000/` and you should see the
+documentation open with a header "Welcome to my amazing app!" and so on.
+
+## What did this demonstrate?
+
+Without Blueprint installed, you would have had to place the above default.nix file containing the mkdocs code inside your main flake.nix file, or link to it manually. But because of Blueprint, your setup will automatically scan a set of predetermined folders (including Packages) for files and find them automatically, making them available to use.
+
+> **Tip:** If you want to see what folders are available, head over to our 
+[folder strutures](folder_structure.md) documentation.
+
+
+# (Optional) Configuring direnv
+
+Included in the initial files created by Blueprint is a filed called .envrc. This file contains code to configure direnv, which allows you to enter a devshell simply by switching to the folder containing your project. That means you don't need to type `nix develop` after entering the folder. Then when you move up and out of the folder, you'll automatically exit the environment.
+
+For more information on configuring this feature, check out our guide at [Configuring Direnv](../guides/configuring_direnv.md)