doc: new mdbook documentation

.github/workflows/mdbook_docs.yml

@@ -0,0 +1,26 @@
+name: Deploy Docs to GitHub Pages
+
+on:
+  push:
+    branches:
+      - doc
+
+jobs:
+  deploy:
+    runs-on: ubuntu-18.04
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Setup mdBook
+        uses: peaceiris/actions-mdbook@v1
+        with:
+          mdbook-version: 'latest'
+
+      - run: mdbook build
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_branch: gh-pages
+          publish_dir: ./book

.gitignore

@@ -2,3 +2,4 @@ result
 up
 hosts/up-*
 .direnv
+book

CONTRIBUTING.md

@@ -1,18 +0,0 @@
-# Pull Requests
-
-While much of your work in this template may be idiosyncratic in nature. Anything
-that might be generally useful to the broader NixOS community can be synced to
-the `template` branch to provide a host of useful NixOS configurations available
-"out of the box". If you wish to contribute such an expression please follow
-these guidelines:
-
-* format your code with [`nixpkgs-fmt`][nixpkgs-fmt]. The default devshell
-  includes a pre-commit hook that does this for you.
-
-* The commit message follows the same semantics as [nixpkgs][nixpkgs].
-  * You can use a `#` symbol to specify ambiguities. For example,
-  `develop#zsh: <rest of commit message>` would tell me that your updating the
-  `zsh` subprofile living under the `develop` profile.
-
-[nixpkgs-fmt]: https://github.com/nix-community/nixpkgs-fmt
-[nixpkgs]: https://github.com/NixOS/nixpkgs

DOC.md

@@ -1,105 +0,0 @@
-## Hosts
-Module declarations dependant on particular machines should be stored in the
-[hosts](hosts) directory. Every file in this directory will be added automatically
-to the the `nixosConfigurations` flake output and thus becomes deployable via
-`nixos-rebuild` and `flk`.
-
-See [`hosts/default.nix`](hosts/default.nix) for the implementation.
-
-## Profiles
-A profile is any directory under [profiles](profiles) containing a `default.nix`
-defining a function that returns a valid NixOS module, with the added restriction
-that no new declarations to the `options` _or_ `config` attributes are allowed
-(use [modules](modules) instead). Their purpose is to provide abstract
-expressions suitable for reuse by multiple deployments. They are perhaps _the_
-key mechanism by which we keep this repo maintainable.
-
-Profiles can have subprofiles which are themselves just profiles that live under
-another. There's no hard rule that everything in the folder must be imported by
-its `default.nix`, so you can also store relevant code that is useful but not
-wanted by default in, say, an `alt.nix`. Importantly, every subdirectory in a
-profile should be independent of its parent. i.e:
-
-```nix
-{
-  # importing `profile` without implicitly importing `some`
-  imports = [ ./profiles/some/profile ];
-}
-```
-
-It is okay for profiles to depend on other profiles so long as they are
-explicitly loaded via `imports`.
-
-## Suites
-
-[Suites](./suites/default.nix) are simple collections of profiles that can be
-directly imported from any host like so:
-```
-{ suites, ... }:
-{
-  imports = suites.mySuite;
-}
-```
-
-You can declare any combination of users and profiles that you wish, providing
-a nice abstraction, free from the idiosyncratic concerns of specific hardware.
-
-## Users
-User declarations belong in the `users` directory.
-
-These are actually just a special case of [profiles](#profiles) attached to
-a particular interactive user. Its primarily for declarations to
-`users.users.<new-user>` where `<new-user>.isNormalUser` is true.
-
-This is a convenient place to import your profiles such that a particular user
-always has a reliable stack. Also [user profiles](./users/profiles) are
-available to create reusable configs across different users.
-
-For convenience, [home-manager][home-manager] is available automatically for
-home directory setup and should only be used from this directory.
-
-## Secrets
-Anything you wish to keep encrypted goes in the `secrets` directory, which is
-created on first entering a `nix-shell`.
-
-Be sure to run `git crypt init`, before committing anything to this directory.
-Be sure to check out git-crypt's [documentation](https://github.com/AGWA/git-crypt)
-if your not familiar. The filter is already set up to encrypt everything in this
-folder by default.
-
-To keep [profiles](profiles) reusable across configurations, secrets should
-only be imported from the `users` or [`hosts`](hosts) directory.
-
-## Cachix
-When using:
-```
-cachix use <your-cachix>
-```
-A file with be created in `/etc/nixos/cachix/your-cachix.nix`. Simply add this
-file to git, and it will be exported so others can use your binary cache
-directly from this flake via `nixosModules.cachix.<your-cachix>`.
-
-
-## Modules, Packages and Overlays
-All expressions in both [modules/list.nix](modules/list.nix) and
-[pkgs/default.nix](pkgs/default.nix) are available globally, anywhere else in the
-repo. They are additionally included in the `nixosModules` and `overlay` flake
-outputs, respectively. Packages are automatically included in the `packages`
-output as well.
-
-The directory structure is identical to nixpkgs to provide a kind of staging area
-for any modules or packages we might be wanting to merge there later. If your not
-familiar or can't be bothered, simply dropping a valid nix file and pointing the
-`default.nix` to it, is all that's really required.
-
-As for overlays, they should be defined in the [overlays](overlays) directory.
-They will be automatically pulled in for use by all configurations. Nix command
-line tools will be able to read overlays from here as well since it is set as
-`nixpkgs-overlays` in `NIX_PATH`. And of course they will be exported via the
-flake output `overlays` as well.
-
-If you wish to use an overlay from an external flake, simply add it to the
-`externOverlays` list in the `let` block of the `outputs` attribute in
-[flake.nix](flake.nix). Same for external modules, add them to `externModules`.
-
-[home-manager]: https://github.com/nix-community/home-manager

SUMMARY.md

@@ -0,0 +1,19 @@
+# Summary
+
+- [Introduction](./doc/introduction.md)
+- [Quick Start](./doc/start/index.md)
+  - [ISO](./doc/start/iso.md)
+  - [From NixOS](./doc/start/from-nixos.md)
+- [Layout](./doc/layout.md)
+  - [Cachix](./cachix/README.md)
+  - [Extern](./extern/README.md)
+  - [Hosts](./hosts/README.md)
+  - [Modules](./modules/README.md)
+  - [Overlays](./overlays/README.md)
+  - [Overrides](./overrides/README.md)
+  - [Packages](./pkgs/README.md)
+  - [Profiles](./profiles/README.md)
+  - [Secrets](./secrets/README.md)
+  - [Suites](./suites/README.md)
+  - [Users](./users/README.md)
+- [flk command](./doc/flk/index.md)

book.toml

@@ -0,0 +1,9 @@
+[book]
+authors = ["Timothy DeHerrera"]
+language = "en"
+multilingual = false
+src = "."
+title = "nixflk docs"
+
+[output.html]
+site-url = "/nixflk/"

cachix/README.md

@@ -0,0 +1,12 @@
+# Cachix
+The cachix directory simple captures the output of `sudo cachix use` for the
+developers personal cache, as well as the nix-community cache. You can easily
+add your own cache, assuming the template lives in /etc/nixos, by simply
+running `sudo cachix use yourcache`.
+
+These caches are only added to the system after a `nixos-rebuild switch`, so it
+is recommended to call `cachix use nrdxp` before the initial deployment, as it
+will save a lot of build time.
+
+In the future, users will be able to skip this step once the ability to define
+the nix.conf within the flake is fully fleshed out upstream.

doc/.gitignore

@@ -0,0 +1 @@
+book

doc/flk/index.md

@@ -0,0 +1 @@
+# flk command

doc/introduction.md

@@ -0,0 +1,33 @@
+# Introduction
+Nixflk is a template which grants a simple way to use, deploy and manage
+[NixOS][nixos] systems for personal and productive use. It does this by
+providing a sane repository structure, integrating several popular projects
+like [home-manager][home-manager], setting clear guidelines, offering useful
+conveniences, and eliminating boilerplate so you can focus on deploying your
+systems.
+
+## Community Profiles
+There are two branches from which to choose: [core][core] and
+[community][community]. The community branch builds on core and includes
+several ready-made profiles for discretionary use.
+
+Every package and NixOS profile declared in community is uploaded to
+[cachix](../cachix), so everything provided is available without building
+anything. This is especially useful for the packages that are
+[overridden](../overrides) from master, as without the cache, rebuilds are
+quite frequent.
+
+### ⚠ Advisory
+Nixflk leverages the [flakes][flakes] feature available via an _experimental_
+branch of [nix][nix]. Until nix 3.0 is released, this project should be
+considered unstable.
+
+# License
+Nixflk is licensed under the [MIT License](https://mit-license.org).
+
+[nix]: https://nixos.org/manual/nix/stable
+[nixos]: https://nixos.org/manual/nixos/stable
+[home-manager]: https://nix-community.github.io/home-manager
+[flakes]: https://nixos.wiki/wiki/Flakes
+[core]: https://github.com/nrdxp/nixflk
+[community]: https://github.com/nrdxp/nixflk/tree/community

doc/layout.md

@@ -0,0 +1,4 @@
+# Layout
+Each of the following sections is a directory in the root of the project
+serving a singular purpose. Select a chapter to read more about its purpose
+and usage.

doc/start/from-nixos.md

@@ -0,0 +1,47 @@
+# From NixOS
+
+## Generate Configuration
+Assuming your happy with your existing partition layout, you can generate a
+basic NixOS configuration for your system using:
+```sh
+flk up
+```
+
+This will make a new file `hosts/up-$(hostname).nix`, which you can edit to
+your liking.
+
+Make sure your `i18n.defaultLocale` and `time.timeZone` are set properly for
+your region. Keep in mind that `networking.hostName` with be automatically
+set to the filename of your hosts file, so `hosts/my-host.nix` will have the
+hostname `my-host`.
+
+Now might be a good time to read the docs on [suites](../../suites) and
+[profiles](../../profiles) and add or create any that you need.
+
+> ##### _Note:_
+> While the `up` sub-command is provided as a convenience to quickly set up and
+> install a "fresh" NixOS system on current hardware, committing these files is
+> discouraged.
+>
+> They are placed in the git staging area automatically because they would be
+> invisible to the flake otherwise, but it is best to move what you need from
+> them directly into a host module of your own making, and commit that instead.
+# Installation
+
+Once your ready to deploy `hosts/my-host.nix`:
+```sh
+flk my-host switch
+```
+
+
+This calls `nixos-rebuild` with sudo to build and install your configuration.
+
+> ##### _Notes:_
+> - Instead of `switch`, you can pass `build`, `test`, `boot`, etc just as with
+>   `nixos-rebuild`.
+>
+> - It is convenient to have the template living at `/etc/nixos` so you can
+>   simply `sudo nixos-rebuild switch` from anywhere on the system, but it is
+>   not required.
+
+

doc/start/index.md

@@ -0,0 +1,38 @@
+# Quick Start
+The only dependency is nix, so make sure you have it [installed][install-nix].
+
+## Get the Template
+Here is a snippet that will get you the template without the git history:
+```sh
+nix-shell https://github.com/nrdxp/nixflk/archive/core.tar.gz -A shell \
+  --run "flk get core"
+
+cd flk
+
+nix-shell
+
+git init
+git add .
+git commit -m init
+
+cachix use nrdxp
+```
+
+This will place you in a new folder named `flk` with git initialized, and a
+nix-shell that provides all the dependencies, including the unstable nix
+version required.
+
+In addition, the [binary cache](../../cachix) is added for faster deployment.
+
+> ##### _Notes:_
+> - You can change `core` to [`community`](../introduction.md#community-profiles)
+>   in the call to `flk get`
+> - Flakes ignore files that have not been added to git, so be sure to stage new
+>   files before building the system.
+
+## Next Steps:
+- [Make installable ISO](./iso.md)
+- [Already on NixOS](./from-nixos.md)
+
+
+[install-nix]: https://nixos.org/manual/nix/stable/#sect-multi-user-installation

doc/start/iso.md

@@ -0,0 +1,11 @@
+# ISO
+
+Making and writing an installable iso for `hosts/NixOS.nix` is as simple as:
+```sh
+flk iso NixOS
+
+dd bs=4M if=result/iso/*.iso of=/dev/$your_installation_device \
+  status=progress oflag=sync
+```
+
+This works for any file matching `hosts/*.nix` excluding `default.nix`.

extern/README.md

@@ -0,0 +1,10 @@
+# External Art
+When you need to use a module, overlay, or pass a value from one of your inputs
+to the rest of your NixOS configuration, [extern][extern] is where you do it.
+
+Modules and overlays are self explanatory, and the `specialArgs` attribute is
+used to extend the arguments passed to all NixOS modules, allowing for
+arbitrary values to be passed from flake inputs to the rest of your
+configuration.
+
+[extern]: https://github.com/nrdxp/nixflk/tree/core/extern/default.nix

extern/default.nix

@@ -12,7 +12,7 @@
 
   # passed to all nixos modules
   specialArgs = {
-    unstableModulesPath = "${master}/nixos/modules";
+    overrideModulesPath = "${override}/nixos/modules";
     hardware = nixos-hardware.nixosModules;
   };
 }

flake.lock

@@ -7,7 +7,7 @@
           "nixos"
         ],
         "nixos-unstable": [
-          "master"
+          "override"
         ],
         "pre-commit-hooks-nix": "pre-commit-hooks-nix"
       },
@@ -93,7 +93,7 @@
         "type": "github"
       }
     },
-    "master": {
+    "override": {
       "locked": {
         "lastModified": 1612717294,
         "narHash": "sha256-V3j1rA4a3Lzf5pdbFHzs9jUcOKB91MFO3X8nMY+lK5c=",
@@ -174,7 +174,7 @@
         "devshell": "devshell",
         "flake-utils": "flake-utils",
         "home": "home",
-        "master": "master",
+        "override": "override",
         "nixos": "nixos",
         "nixos-hardware": "nixos-hardware",
         "nur": "nur"

flake.nix

@@ -3,9 +3,7 @@
 
   inputs =
     {
-      # Once desired, bump master's locked revision:
-      # nix flake update --update-input master
-      master.url = "nixpkgs/master";
+      override.url = "nixpkgs/master";
       nixos.url = "nixpkgs/release-20.09";
       home.url = "github:nix-community/home-manager/release-20.09";
       home.inputs.nixpkgs.follows = "nixos";
@@ -14,7 +12,7 @@
       nixos-hardware.url = "github:nixos/nixos-hardware";
       ci-agent.url = "github:hercules-ci/hercules-ci-agent";
       ci-agent.inputs.nixos-20_09.follows = "nixos";
-      ci-agent.inputs.nixos-unstable.follows = "master";
+      ci-agent.inputs.nixos-unstable.follows = "override";
     };
 
   outputs =
@@ -22,7 +20,7 @@
     , ci-agent
     , home
     , nixos
-    , master
+    , override
     , flake-utils
     , nur
     , devshell

hosts/README.md

@@ -0,0 +1,43 @@
+# Hosts
+
+Nix flakes contain an output called `nixosConfigurations` declaring an
+attribute set of valid NixOS systems. To simplify the management and creation
+of these hosts, nixflk automatically imports every _.nix_ file inside this
+directory to the mentioned attribute set, applying the projects defaults to
+each. The only hard requirement is that the file contain a valid NixOS module.
+
+As an example, a file `hosts/system.nix` will be available via the flake
+output `nixosConfigurations.system`. You can have as many hosts as you want
+and all of them will be automatically imported based on their name.
+
+For each host, the configuration automatically sets the `networking.hostName`
+attribute to the name of the file minus the _.nix_ extension. This is for
+convenience, since `nixos-rebuild` automatically searches for a configuration
+matching the current systems hostname if one is not specified explicitly.
+
+It is recommended that the host modules only contain configuration information
+specific to a particular piece of hardware. Anything reusable across machines
+is best saved for [profile modules](../profiles).
+
+This is a good place to import sets of profiles, called [suites](../suites),
+that you intend to use on your machine.
+
+Additionally, this is the perfect place to import anything you might need from
+the [nixos-hardware][nixos-hardware] repository.
+
+## Example
+
+`hosts/librem.nix`:
+```nix
+{ suites, hardware, ... }:
+{
+  imports = suites.laptop ++ [ hardware.purism-librem-13v3 ];
+
+  boot.loader.systemd-boot.enable = true;
+  boot.loader.efi.canTouchEfiVariables = true;
+
+  fileSystems."/" = { device = "/dev/disk/by-label/nixos"; };
+}
+```
+
+[nixos-hardware]: https://github.com/NixOS/nixos-hardware

hosts/default.nix

@@ -1,6 +1,6 @@
 { lib
 , nixos
-, master
+, override
 , nixos-hardware
 , pkgs
 , self
@@ -24,15 +24,15 @@ let
         let
           core = import ../profiles/core;
 
-          modOverrides = { config, unstableModulesPath, ... }:
+          modOverrides = { config, overrideModulesPath, ... }:
             let
-              unstable = import ../unstable;
-              inherit (unstable) modules disabledModules;
+              overrides = import ../overrides;
+              inherit (overrides) modules disabledModules;
             in
             {
               disabledModules = modules ++ disabledModules;
               imports = map
-                (path: "${unstableModulesPath}/${path}")
+                (path: "${overrideModulesPath}/${path}")
                 modules;
             };
 
@@ -44,7 +44,7 @@ let
 
             networking.hostName = hostName;
             nix.nixPath = [
-              "nixos-unstable=${master}"
+              "nixos-unstable=${override}"
               "nixos=${nixos}"
               "nixpkgs=${nixos}"
             ];
@@ -52,7 +52,6 @@ let
             nixpkgs = { inherit pkgs; };
 
             nix.registry = {
-              master.flake = master;
               nixflk.flake = self;
               nixpkgs.flake = nixos;
             };

lib/default.nix

@@ -83,11 +83,11 @@ in
       (system:
         let
           extern = import ../extern { inherit inputs; };
-          unstable = pkgImport inputs.master [ ] system;
-          overrides = (import ../unstable).packages;
+          overridePkgs = pkgImport inputs.override [ ] system;
+          overridesOverlay = (import ../overrides).packages;
 
           overlays = [
-            (overrides unstable)
+            (overridesOverlay overridePkgs)
             self.overlay
             (final: prev: {
               lib = (prev.lib or { }) // {
@@ -173,7 +173,7 @@ in
       cachixAttrs = { inherit cachix; };
 
       # modules
-      moduleList = import ../modules/list.nix;
+      moduleList = import ../modules/module-list.nix;
       modulesAttrs = pathsToImportedAttrs moduleList;
 
     in

modules/README.md

@@ -0,0 +1,79 @@
+# Modules
+The modules directory is a replica of nixpkg's NixOS [modules][nixpkgs-modules]
+, and follows the same semantics. This allows for trivial upstreaming into
+nixpkgs proper once your module is sufficiently stable.
+
+All modules linked in _module-list.nix_ are automatically exported via
+`nixosModules.<file-basename>`, and imported into all [hosts](../hosts).
+
+
+> ##### _Note:_
+> This is reserved for declaring brand new module options. If you just want to
+> declare a coherent configuration of already existing and related NixOS options
+> , use [profiles](../profiles) instead.
+
+## Semantics
+In case you've never written a module for nixpkgs before, here is a brief
+outline of the process.
+
+### Declaration
+modules/services/service-category/my-service.nix:
+```nix
+{ config, lib, ... }:
+let
+  cfg = config.services.myService;
+in
+{
+  options.services.myService = {
+    enable = lib.mkEnableOption "Description of my new service.";
+
+    # additional options ...
+  };
+
+  config = lib.mkIf cfg.enable {
+    # implementation ...
+  };
+}
+```
+
+### Import
+modules/module-list.nix:
+```nix
+[
+  ./services/service-category/my-service.nix
+]
+```
+
+## Usage
+
+### Internal
+profiles/profile-category/my-profile.nix:
+```nix
+{ ... }:
+{
+  services.MyService.enable = true;
+}
+```
+
+### External
+flake.nix:
+```nix
+{
+  # inputs omitted
+
+  outputs = { self, nixflk, nixpkgs, ... }: {
+    nixosConfigurations.myConfig = nixpkgs.lib.nixosSystem {
+      system = "...";
+
+      modules = [
+        nixflk.nixosModules.my-service
+        ({ ... }: {
+          services.MyService.enable = true;
+        })
+      ];
+    };
+  };
+}
+```
+
+[nixpkgs-modules]: https://github.com/NixOS/nixpkgs/tree/master/nixos/modules

overlays/README.md

@@ -0,0 +1,25 @@
+# Overlays
+Writing overlays is a common occurence when using a NixOS system. Therefore,
+we want to keep the process as simple and straightforward as possible.
+
+Any _.nix_ files declared in this directory will be assumed to be a valid
+overlay, and will be automatically imported into all [hosts](../hosts), and
+exported via `overlays.<file-basename>` _as well as_
+`packages.<system>.<pkgName>` (for valid systems), so all you have to do is
+write it.
+
+## Example
+overlays/kakoune.nix:
+```nix
+final: prev: {
+  kakoune = prev.kakoune.override {
+    configure.plugins = with final.kakounePlugins; [
+      (kak-fzf.override { fzf = final.skim; })
+      kak-auto-pairs
+      kak-buffers
+      kak-powerline
+      kak-vertical-selection
+    ];
+  };
+}
+```

overrides/README.md

@@ -0,0 +1,46 @@
+# Overrides
+By default, the NixOS systems are based on the latest release. While it is
+trivial to change this to nixos-unstable or any other branch of nixpkgs by
+changing the flake url, sometimes all we want is a single package from another
+branch.
+
+This is what the overrides are for. By default, they are pulled directly from
+nixpkgs/master, but you can change the `override` flake input url to
+nixos-unstable, or even a specific sha revision.
+
+
+## Example
+
+### Packages
+The override packages are defined as a regular overlay with an extra arguement
+`pkgs`. This refers to the packages built from the `override` flake.
+
+Pulling the manix package from the override flake:
+```nix
+{
+  packages = pkgs: final: prev: {
+    inherit (pkgs) manix;
+  };
+}
+```
+
+### Modules
+
+You can also pull modules from override. Simply specify their path relative to
+the nixpkgs [modules][nixpkgs-modules] directory. The old version will be added
+to `disabledModules` and the new version imported into the configuration.
+
+Pulling the zsh module from the override flake:
+```nix
+{
+  modules = [ "programs/zsh/zsh.nix" ];
+}
+```
+
+> ##### _Note:_
+> Sometimes a modules name will change from one branch to another. This is what
+> the `disabledModules` list is for. If the module name changes, the old
+> version will not automatically be disabled, so simply put it's old name in
+> this list to disable it.
+
+[nixpkgs-modules]: https://github.com/NixOS/nixpkgs/tree/master/nixos/modules

overrides/default.nix

@@ -1,11 +1,12 @@
+# override defaults to nixpkgs/master
 {
-  # modules to pull from master, stable version is automatically disabled
+  # modules to pull from override, stable version is automatically disabled
   modules = [ ];
 
-  # if a modules name changed in master, add the old name here
+  # if a modules name changed in override, add the old name here
   disabledModules = [ ];
 
-  # packages pulled from master
+  # packages pulled from override
   packages = pkgs: final: prev: {
     inherit (pkgs)
       dhall

pkgs/README.md

@@ -0,0 +1,59 @@
+# Packages
+Similar to [modules](../modules), the pkgs directory mirrors the upstream
+[nixpkgs/pkgs][pkgs], and for the same reason; if you ever want to upstream
+your package, it's as simple as dropping it into the nixpkgs/pkgs directory.
+
+The only minor difference is that, instead of adding the `callPackage` call to
+`all-packages.nix`, you just add it the the _default.nix_ in this directory,
+which is defined as a simple overlay.
+
+This overlay is set as the default `overlay` output attribute for the flake.
+And all the packages are exported via `packages.<system>.<pkg-name>`, for all
+the supported systems listed in the package's `meta.platforms` attribute.
+
+And, as usual, every package in the overlay is also available to any NixOS
+[host](../hosts).
+
+## Example
+pkgs/development/libraries/libinih/default.nix:
+```nix
+{ stdenv, meson, ninja, fetchFromGitHub, ... }:
+let version = "r50";
+in
+stdenv.mkDerivation {
+  pname = "libinih";
+  inherit version;
+
+  src = fetchFromGitHub {
+    owner = "benhoyt";
+    repo = "inih";
+    rev = "${version}";
+    hash = "sha256-GF+TVEysaXJxSBBjMsTr2IQvRKlzdEu3rlPQ88PE3nI=";
+  };
+
+  buildInputs = [ meson ninja ];
+
+  mesonFlags = ''
+    -Ddefault_library=shared
+    -Ddistro_install=true
+  '';
+
+  meta = with stdenv.lib; {
+    description = "Simple .INI file parser in C";
+    homepage = "https://github.com/benhoyt/inih";
+    maintainers = [ maintainers.nrdxp ];
+    license = licenses.bsd3;
+    platforms = platforms.all;
+    inherit version;
+  };
+}
+```
+
+pkgs/default.nix:
+```nix
+final: prev: {
+  libinih = prev.callPackage ./development/libraries/libinih { };
+}
+```
+
+[pkgs]: https://github.com/NixOS/nixpkgs/tree/master/pkgs

profiles/README.md

@@ -0,0 +1,48 @@
+# Profiles
+Profiles are simply NixOS modules which contain generic expressions suitable
+for any host. A good example is the configuration for a text editor, or
+window manager. If you need some concrete examples, just checkout the
+community [branch](https://github.com/nrdxp/nixflk/tree/community/profiles).
+
+## Constraints
+For the sake of consistency, there are a few minor constraints. First of all, a
+profile should always be defined in a `default.nix`, and it should always be a
+a function taking a single attribute set as an argument, and returning a NixOS
+module which does not define any new module options. If you need to make new
+module option declarations, just use [modules](../modules).
+
+These restrictions help simplify the import logic used to pass profles to
+[suites](../suites).
+
+### Example
+#### Correct ✔
+profiles/develop/default.nix:
+```nix
+{  ... }:
+{
+  programs.zsh.enable = true;
+}
+```
+
+#### Incorrect ❌
+profiles/develop.nix:
+```nix
+{
+  options = {};
+}
+```
+
+## Subprofiles
+Profiles can also define subprofiles. They follow the same constraints outlined
+above. A good top level profile should be a high level concern, such a your
+personal development environment, and the subprofiles should be more concrete
+program configurations such as your text editor, and shell configs. This way,
+you can either pull in the whole development profile, or pick and choose
+individual programs.
+
+## Conclusion
+Profiles are the most important concept in nixflk. They allow us to keep our
+nix expressions self contained and modular. This way we can maximize reuse
+while minimizing boilerplate. Always strive to keep your profiles as generic
+and modular as possible. Anything machine specific belongs in your
+[host](../hosts) files.

secrets/.gitattributes

@@ -1,2 +1,3 @@
 * filter=git-crypt diff=git-crypt
 .gitattributes !filter !diff
+README.md !filter !diff

secrets/README.md

@@ -0,0 +1,18 @@
+# Secrets
+Secrets are managed using [git-crypt][git-crypt] so you can keep your flake in
+a public repository like GitHub without exposing your password or other
+sensitive data.
+
+By default, everything in the secrets folder is automatically encrypted. Just
+be sure to run `git-crypt init` before putting anything in here.
+
+> ##### _Note:_
+> Currently, there is [no mechanism][secrets-issue] in nix to deploy secrets
+> within the nix/store so, if they end up in the nix/store after deployment, they
+> will be world readable on that machine.
+>
+> The author of nixflk intends to implement a workaround for this situation in
+> the near future, but for the time being, simple be aware of this.
+
+[git-crypt]: https://github.com/AGWA/git-crypt
+[secrets-issue]: https://github.com/NixOS/nix/issues/8

shell/default.nix

@@ -23,7 +23,6 @@ pkgs.devshell.mkShell {
     nixos-install
     nixos-generate-config
     nixos-enter
-    mdbook
   ];
 
   env = { inherit name; };

suites/README.md

@@ -0,0 +1,24 @@
+# Suites
+Suites provide a mechanism for users to easily combine and name collecitons of
+profiles. For good examples, check out the suites defined in the community
+[branch](https://github.com/nrdxp/nixflk/blob/community/suites/default.nix).
+
+In the future, we will use suites as a mechanism for deploying various machine
+types which don't depend on hardware, such as vm's and containers.
+
+## Definition
+```nix
+rec {
+  workstation = [ profiles.develop profiles.graphical users.nixos ];
+  mobileWS = workstation ++ [ profiles.laptop ];
+}
+```
+
+## Usage
+`hosts/my-laptop.nix`:
+```nix
+{ suites, ... }:
+{
+  imports = suites.mobileWS;
+}
+```

users/README.md

@@ -0,0 +1,51 @@
+# Users
+
+Users are a special case of [profiles](../profiles) that define system
+users and [home-manager][home-manager] configurations. For your convenience,
+home manager is wired in by default so all you have to worry about is declaring
+your users. For a fully fleshed out example, check out the developers personal
+[branch](https://github.com/nrdxp/nixflk/tree/nrd/users/nrd/default.nix).
+
+## Basic Usage
+`users/myuser/default.nix`:
+```nix
+{ ... }:
+{
+  users.users.myuser = {
+    isNormalUser = true;
+  };
+
+  home-manager.users.myuser = {
+    programs.mpv.enable = true;
+  };
+}
+
+```
+
+## External Usage
+You can easily use the defined home-manager configurations outside of NixOS
+using the `hmActivations` meta-package defined in the flakes `legacyPackages`
+output. The [flk](../doc/flk) helper script makes this even easier.
+
+This is great for keeping your environment consistent across Unix systems,
+including OSX.
+
+### From within the projects devshell:
+```sh
+# builds the nixos user defined in the NixOS host
+flk home NixOS nixos
+
+# build and activate
+flk home NixOS nixos switch
+```
+
+### Manually from outside the project:
+```sh
+# build
+nix build "github:nrdxp/nixflk#hmActivationPackages.NixOS.nixos"
+
+# activate
+./result/activate && unlink result
+```
+
+[home-manager]: https://nix-community.github.io/home-manager