- For a general introduction to modules, you can read Writing Modules in the NixOS manual, though it goes into NixOS specifics quite quickly. Instead of services.<name>.*, etc, we have our own options.
-
-
-
- Writing modules in a distributed ecosystem can be a bit different. If you're inclined to write to some other module's options, consider whether those will be loaded and whether your integration idea is always desirable. If it's not always desirable, consider splitting it off into an extra module, e.g. flakeModules.someOther. Otherwise check if it's loaded: lib.optionalAttrs (options?some.other.option). You can ask @roberth on GitHub.
-
-
-
-
-
\ No newline at end of file
diff --git a/site/options.xsl b/site/options.xsl
index c1920d6..830825d 100644
--- a/site/options.xsl
+++ b/site/options.xsl
@@ -14,6 +14,10 @@
<xsl:value-of select="$title"/>
+ Overview:
+
+
+
diff --git a/site/src/SUMMARY.md b/site/src/SUMMARY.md
new file mode 100644
index 0000000..2a14b8a
--- /dev/null
+++ b/site/src/SUMMARY.md
@@ -0,0 +1,11 @@
+# Summary
+
+- [Introduction](./README.md)
+- [Getting Started](./getting-started.md)
+- [Working with `system`](./system.md)
+- [Reference Documentation](./module-arguments.md)
+ - [Module Arguments](./module-arguments.md)
+ - [Options](./options/flake-parts.md)
+ - [Core `flake-parts`](./options/flake-parts.md)
+ - [`hercules-ci-effects`](./options/hercules-ci-effects.md)
+ - [`pre-commit-hooks.nix`](./options/pre-commit-hooks-nix.md)
diff --git a/site/src/getting-started.md b/site/src/getting-started.md
new file mode 100644
index 0000000..1cd713d
--- /dev/null
+++ b/site/src/getting-started.md
@@ -0,0 +1,38 @@
+
+# Getting Started
+
+## New flake
+
+If your project does not have a flake yet:
+
+```console
+nix flake init -t github:hercules-ci/flake-parts
+```
+
+## Existing flake
+
+Otherwise, add the input,
+
+```
+ flake-parts.url = "github:hercules-ci/flake-parts";
+```
+
+then slide `mkFlake` between your outputs function head and body,
+
+```
+ outputs = { self, flake-parts, ... }:
+ flake-parts.lib.mkFlake { inherit self; } {
+ flake = {
+ # Put your original flake attributes here.
+ };
+ systems = [
+ # systems for which you want to build the `perSystem` attributes
+ "x86_64-linux"
+ # ...
+ ];
+ perSystem = { config, ... }: {
+ };
+ };
+```
+
+Now you can start using the flake-parts options.
diff --git a/site/src/intro-continued.md b/site/src/intro-continued.md
new file mode 100644
index 0000000..e398c97
--- /dev/null
+++ b/site/src/intro-continued.md
@@ -0,0 +1,7 @@
+
+
+# This documentation
+
+You can find guides and the options reference in the menu (top left).
+
+A site wide search is available by typing `s`.
diff --git a/site/src/module-arguments.md b/site/src/module-arguments.md
new file mode 100644
index 0000000..438305a
--- /dev/null
+++ b/site/src/module-arguments.md
@@ -0,0 +1,58 @@
+
+# Module Arguments
+
+The module system allows modules and submodules to be defined using plain
+attribute sets, or functions that return attribute sets. When a module is a
+function, various attributes may be passed to it.
+
+# Top-level Module Arguments
+
+Top-level refers to the module passed to `mkFlake`, or any of the modules
+imported into it using `imports`.
+
+The standard module system arguments are available in all modules and submodules. These are chiefly `config`, `options`, `lib`.
+
+## `getSystem`
+
+A function from [system](./system.md) string to the `config` of the appropriate `perSystem`.
+
+## `moduleWithSystem`
+
+A function that brings the `perSystem` module arguments.
+This allows a module to reference the defining flake without introducing
+global variables.
+
+```nix
+{ moduleWithSystem, ... }:
+{
+ nixosModules.default = moduleWithSystem (
+ perSystem@{ config }: # NOTE: only explicit params will be in perSystem
+ nixos@{ ... }:
+ {
+ services.foo.package = perSystem.config.packages.foo;
+ imports = [ ./nixos-foo.nix ];
+ }
+ );
+}
+```
+
+## `withSystem`
+
+Enter the scope of a system. Worked example:
+
+```nix
+{ withSystem, ... }:
+{
+ # perSystem = ...;
+
+ nixosConfigurations.foo = withSystem "x86_64-linux" (ctx@{ pkgs, ... }:
+ pkgs.nixos ({ config, lib, packages, pkgs, ... }: {
+ _module.args.packages = ctx.config.packages;
+ imports = [ ./nixos-configuration.nix ];
+ services.nginx.enable = true;
+ environment.systemPackages = [
+ packages.hello
+ ];
+ }));
+}
+```
diff --git a/site/src/system.md b/site/src/system.md
new file mode 100644
index 0000000..64ed635
--- /dev/null
+++ b/site/src/system.md
@@ -0,0 +1,20 @@
+
+# `system`
+
+In Nix, "system" generally refers to the cpu-os string, such as `"x86_64-linux"`.
+
+In Flakes specifically, these strings are used as attribute names, so that the
+Nix CLI can find a derivation for the right platform.
+
+Many things, such as packages, can exist on multiple systems. For these, use
+the [`perSystem`](options/flake-parts.html#opt-perSystem) submodule.
+
+Other things do not exist on multiple systems. Examples are the configuration
+of a specific machine, or a the execution of a deployment. These are not
+written in `perSystem`, but in other top-level options, or directly into the
+flake outputs' top level (e.g. [`flake.nixosConfigurations`](options/flake-parts.html#opt-flake.nixosConfigurations)).
+
+Such top-level entities typically do need to read packages, etc that are defined
+in `perSystem`. Instead of reading them from `config.flake.packages..`,
+it may be more convenient to bring all `perSystem` definitions for a system into
+scope, using [`withSystem`](module-arguments.html#withsystem).