diff --git a/src/components/CookieConsent.astro b/src/components/CookieConsent.astro
new file mode 100644
index 00000000..6268113d
--- /dev/null
+++ b/src/components/CookieConsent.astro
@@ -0,0 +1,38 @@
+
+
+
+ We use a single, first-party analytics cookie to focus our limited time
+ and energy on the most important documentation. Check out our
+
+ privacy policy
+
+ .
+
+ This document is a work in progress. It's intended to provide a
+ brief definition or overview and nothing more. We'll be iterating
+ on this content heavily in the coming weeks and months.
+
diff --git a/src/components/Posthog.astro b/src/components/Posthog.astro
new file mode 100644
index 00000000..9bd45b3b
--- /dev/null
+++ b/src/components/Posthog.astro
@@ -0,0 +1,9 @@
+
diff --git a/src/components/QuickStart.astro b/src/components/QuickStart.astro
new file mode 100644
index 00000000..4d9b960b
--- /dev/null
+++ b/src/components/QuickStart.astro
@@ -0,0 +1,31 @@
+
+
+
+ We recommend starting with the
+ Nix quick start and consulting concept docs primarily
+ for clarification. Feel free to click
+ x to the right to disable this notification
+ on all concept docs.
+
- We use a single, first-party analytics cookie to focus our limited time
- and energy on the most important documentation. Check out our
- privacy policy.
-
- This document is a work in progress. It's intended to provide a brief
- definition or overview and nothing more. We'll be iterating on this
- content heavily in the coming weeks and months.
-
- We recommend starting with the
- Nix quick start and consulting concept docs
- primarily for clarification. Feel free to click
- x to the right to disable this
- notification on all concept docs.
-
-
-
-
diff --git a/src/components/mdx/stateful/SpecificLanguage.vue b/src/components/mdx/stateful/SpecificLanguage.vue
deleted file mode 100644
index 4c1d9d01..00000000
--- a/src/components/mdx/stateful/SpecificLanguage.vue
+++ /dev/null
@@ -1,14 +0,0 @@
-
-
-
-
-
diff --git a/src/components/mdx/stateful/SpecificSystem.vue b/src/components/mdx/stateful/SpecificSystem.vue
deleted file mode 100644
index 8c20c39c..00000000
--- a/src/components/mdx/stateful/SpecificSystem.vue
+++ /dev/null
@@ -1,14 +0,0 @@
-
-
-
-
-
diff --git a/src/components/mdx/stateful/System.vue b/src/components/mdx/stateful/System.vue
deleted file mode 100644
index 44915969..00000000
--- a/src/components/mdx/stateful/System.vue
+++ /dev/null
@@ -1,7 +0,0 @@
-
- {{ system }}
-
-
-
diff --git a/src/components/mdx/stateful/Systems.vue b/src/components/mdx/stateful/Systems.vue
deleted file mode 100644
index ff017688..00000000
--- a/src/components/mdx/stateful/Systems.vue
+++ /dev/null
@@ -1,14 +0,0 @@
-
-
-
-
-
diff --git a/src/briefs/nix-installer-differences.mdx b/src/content/briefs/nix-installer-differences.mdx
similarity index 100%
rename from src/briefs/nix-installer-differences.mdx
rename to src/content/briefs/nix-installer-differences.mdx
diff --git a/src/pages/concepts/caching.mdx b/src/content/concepts/caching.mdx
similarity index 65%
rename from src/pages/concepts/caching.mdx
rename to src/content/concepts/caching.mdx
index a4062c29..92d05947 100644
--- a/src/pages/concepts/caching.mdx
+++ b/src/content/concepts/caching.mdx
@@ -4,35 +4,32 @@ wip: true
snippet: |
The mechanism whereby [Nix](/concepts/nix) uses already-built artifacts rather than building some artifacts unnecessarily
related: ["closures", "derivations", "nix-store"]
-externalSources: [
- {
- title: "Binary cache",
- href: "https://wiki.nixos.org/wiki/Binary_Cache",
- source: {
- title: "The NixOS Wiki",
- href: "https://wiki.nixos.org"
- }
- },
- {
- title: "Setting up a private Nix cache for fun and profit",
- href: "https://channable.com/tech/setting-up-a-private-nix-cache-for-fun-and-profit",
- source: {
- title: "The Channable blog",
- href: "https://www.channable.com/tech"
- }
- },
- {
- title: "Serving a Nix store via HTTP",
- href: "https://nixos.org/manual/nix/stable/package-management/binary-cache-substituter",
- source: {
- title: "The Nix manual",
- href: "https://nixos.org/manual/nix/stable"
- }
- }
-]
+externalSources:
+ [
+ {
+ title: "Binary cache",
+ href: "https://wiki.nixos.org/wiki/Binary_Cache",
+ source: { title: "The NixOS Wiki", href: "https://wiki.nixos.org" },
+ },
+ {
+ title: "Setting up a private Nix cache for fun and profit",
+ href: "https://channable.com/tech/setting-up-a-private-nix-cache-for-fun-and-profit",
+ source:
+ { title: "The Channable blog", href: "https://www.channable.com/tech" },
+ },
+ {
+ title: "Serving a Nix store via HTTP",
+ href: "https://nixos.org/manual/nix/stable/package-management/binary-cache-substituter",
+ source:
+ {
+ title: "The Nix manual",
+ href: "https://nixos.org/manual/nix/stable",
+ },
+ },
+ ]
---
-By default, Nix uses *caching* to make [building packages][packages] faster and more efficient.
+By default, Nix uses _caching_ to make [building packages][packages] faster and more efficient.
This in turn makes other Nix operations that involve building packages, like creating [development environments][dev] and standing up [NixOS] environments, faster and more efficient as well.
## Building vs. caching
@@ -44,24 +41,27 @@ Here's what Nix does whenever it realises a derivation:
1. It computes a hash for the derivation and, using that hash, a [Nix store path][store-paths] of this form (for a hypothetical Git package):
-
+
1. With a store path in hand, Nix determines whether the derivation has already been built.
- First, Nix checks the configured [Nix store][store] to see if the path `/nix/store/f8f72p3xxr20k111mpg4kk93i4cp74qb/git-2.37.0` already exists.
- If so, it uses that rather than building it.
- If not...
+ First, Nix checks the configured [Nix store][store] to see if the path `/nix/store/f8f72p3xxr20k111mpg4kk93i4cp74qb/git-2.37.0` already exists.
+ If so, it uses that rather than building it.
+ If not...
1. It checks a if the store path exists in a configured [binary cache](#binary-caches).
1. If the store path exists neither in a configured [Nix store][store] nor in a configured [binary cache](#binary-caches), Nix builds the derivation from scratch, recursively following all of the steps in this list, using already-realised packages whenever possible and building only what is necessary.
-
-Without caching, [realisation][realising] would involve always building everything from scratch every single time, which would make Nix a much less efficient—and thereby much less compelling!—package manager and build tool.
+
+ Without caching, [realisation][realising] would involve always building
+ everything from scratch every single time, which would make Nix a much less
+ efficient—and thereby much less compelling!—package manager and
+ build tool.
## Binary caches
-In addition to the local [Nix store][store], you can also cache Nix artifacts using remote Nix stores called *binary caches* that serve pre-built binaries via HTTP.
+In addition to the local [Nix store][store], you can also cache Nix artifacts using remote Nix stores called _binary caches_ that serve pre-built binaries via HTTP.
For the most part, binary caches work just like the Nix store, enabling Nix to quickly determine whether something has already been built on the basis of a derivation's Nix store path.
By default, Nix uses [cache.nixos.org][cache] as a binary cache, which is open to all and populated by continuous integration systems.
diff --git a/src/pages/concepts/channels.mdx b/src/content/concepts/channels.mdx
similarity index 93%
rename from src/pages/concepts/channels.mdx
rename to src/content/concepts/channels.mdx
index 4a3ffa53..8e74d78e 100644
--- a/src/pages/concepts/channels.mdx
+++ b/src/content/concepts/channels.mdx
@@ -32,8 +32,7 @@ externalSources: [
]
---
-
-A *Nix channel* is a mechanism used by the legacy Nix CLI to keep [Nixpkgs] up to date.
+A _Nix channel_ is a mechanism used by the legacy Nix CLI to keep [Nixpkgs] up to date.
In the new Nix CLI, channels have been replaced by [flakes].
## How do channels work?
@@ -43,13 +42,13 @@ As a convenience, you can also use the URL syntax `channel:{name}`, which is exp
You can configure Nix to fetch a channel automatically:
-```shell
+```shell title="Add a channel"
nix-channel --add https://nixos.org/channels/nixos-unstable
```
You can then run this to have Nix fetch all channels that you've configured:
-```shell
+```shell title="Update all channels"
nix-channel --update
```
@@ -60,7 +59,7 @@ You can find more information about channels in the [Nix manual][manual].
## Examples of channels
| Channel URL | Release date | Description |
-|--------------------------------|----------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| ------------------------------ | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `channel:nixos-22.11` | Initially released in November of 2022 and updated for 6 months afterwards | A stable version of NixOS, released in November of 2022. Security patches and updates will be backported, but no new applications, or breaking changes will be applied |
| `channel:nixos-unstable` | Frequently updated | A rolling release channel of NixOS, which is updated whenever a set of important packages builds on Hydra. Security updates, new packages, and new modules will frequently appear on your computer, and breaking changes may occur |
| `channel:nixos-unstable-small` | Same as `nixos-unstable`, but even more frequently | A rolling release channel similar to `nixos-unstable` but with a smaller set of packages that are tested. This means this channel is updated more frequently, but may have some broken packages on it as well |
diff --git a/src/pages/concepts/closures.mdx b/src/content/concepts/closures.mdx
similarity index 87%
rename from src/pages/concepts/closures.mdx
rename to src/content/concepts/closures.mdx
index 380b2a74..f645c956 100644
--- a/src/pages/concepts/closures.mdx
+++ b/src/content/concepts/closures.mdx
@@ -5,7 +5,7 @@ snippet: A Nix package's dependency tree
related: ["derivations", "packages"]
---
-In Nix, a [package]'s *closure* encapsulates all of the packages required to [build or run](#build-vs-run) it (as well as the packages required to build those packages, and so on).
+In Nix, a [package]'s _closure_ encapsulates all of the packages required to [build or run](#build-vs-run) it (as well as the packages required to build those packages, and so on).
A package can have zero packages in its closure, because no other packages are required to build it, or it can have many.
Whenever you build a package, Nix always [realises] its entire closure in a [sandboxed] environment.
@@ -13,8 +13,8 @@ Whenever you build a package, Nix always [realises] its entire closure in a [san
Nix closures come in two different types:
-- *Build-time* closures include everything necessary to build the package.
-- *Runtime* closures include everything necessary to run the package.
+- _Build-time_ closures include everything necessary to build the package.
+- _Runtime_ closures include everything necessary to run the package.
To give an example, let's say that you're using Nix to build [Firefox] because you want to install and run it on your machine.
The build-time closure for Firefox would include [GCC] because you can't build Firefox without it.
@@ -24,7 +24,7 @@ When you see mentions of Nix closures in Nix documentation and other places, run
## Closure bloat
-If you include things that a package doesn't need in its closure, you end up with a waste of resources—time, disk space, and network bandwidth—known as *closure bloat*.
+If you include things that a package doesn't need in its closure, you end up with a waste of resources—time, disk space, and network bandwidth—known as _closure bloat_.
Nix always [realises] whatever you tell it to and doesn't have any built-in mechanisms to prevent closure bloat.
The solution to closure bloat is vigilance—you should always vet the [derivations] you create to ensure that every package you include in a derivation is truly required to build or run the desired package.
diff --git a/src/pages/concepts/declarative.mdx b/src/content/concepts/declarative.mdx
similarity index 54%
rename from src/pages/concepts/declarative.mdx
rename to src/content/concepts/declarative.mdx
index 7c709efe..79e3db08 100644
--- a/src/pages/concepts/declarative.mdx
+++ b/src/content/concepts/declarative.mdx
@@ -4,37 +4,29 @@ wip: true
snippet: |
A programming paradigm used by [Nix](/concepts/nix) that emphasizes *what* you want to build rather than *how* things are built
related: ["reproducibility"]
-externalSources: [
- {
- title: "Declarative programming",
- href: "https://en.wikipedia.org/wiki/Declarative_programming",
- source: {
- title: "Wikipedia",
- href: "https://wikipedia.org"
- }
- },
- {
- title: "Declarative vs. imperative programming",
- href: "https://dev.to/ruizb/declarative-vs-imperative-4a7l",
- source: {
- title: "Benoit Ruiz's blog",
- href: "https://dev.to/ruizb"
- }
- },
- {
- title: "Declarative vs imperative programming: 5 key differences",
- href: "https://educative.io/blog/declarative-vs-imperative-programming",
- source: {
- title: "educative",
- href: "https://educative.io/"
- }
- }
-]
+externalSources:
+ [
+ {
+ title: "Declarative programming",
+ href: "https://en.wikipedia.org/wiki/Declarative_programming",
+ source: { title: "Wikipedia", href: "https://wikipedia.org" },
+ },
+ {
+ title: "Declarative vs. imperative programming",
+ href: "https://dev.to/ruizb/declarative-vs-imperative-4a7l",
+ source: { title: "Benoit Ruiz's blog", href: "https://dev.to/ruizb" },
+ },
+ {
+ title: "Declarative vs imperative programming: 5 key differences",
+ href: "https://educative.io/blog/declarative-vs-imperative-programming",
+ source: { title: "educative", href: "https://educative.io/" },
+ },
+ ]
---
-In *declarative programming* a user instructs the computer *what* to do, not *how* to do it.
+In _declarative programming_ a user instructs the computer _what_ to do, not _how_ to do it.
-The result of this is that often a final system is described as it *should exist*.
+The result of this is that often a final system is described as it _should exist_.
A management program (in this case Nix) can then construct a path towards the final output
and do the necessary steps in the required order, without a user having to worry about what exactly is happening and when.
@@ -43,5 +35,5 @@ Nix follows declarative principles in the way that package definitions (or [deri
Under the hood, some parts of packages still have to be written imperatively, but by wrapping these parts in declarative layers,
users of the upper layers don't have to be aware of what is happening below the surface.
-Essentially: one user can solve a problem *once*,
+Essentially: one user can solve a problem _once_,
and many people can then benefit from that solution without needing to know how exactly it works (unless they want to).
diff --git a/src/pages/concepts/derivations.mdx b/src/content/concepts/derivations.mdx
similarity index 76%
rename from src/pages/concepts/derivations.mdx
rename to src/content/concepts/derivations.mdx
index cbc489ca..961f411a 100644
--- a/src/pages/concepts/derivations.mdx
+++ b/src/content/concepts/derivations.mdx
@@ -4,35 +4,36 @@ wip: true
snippet: |
Build instructions for Nix [packages](/concepts/packages) expressed using the [Nix language](/concepts/nix-language)
related: ["caching", "nix-store", "packages", "realisation"]
-externalSources: [
- {
- title: "Derivations",
- href: "https://nixos.org/manual/nix/stable/language/derivations",
- source: {
- title: "The Nix manual",
- href: "https://nixos.org/manual/nix/stable"
- }
- },
- {
- title: "How to learn Nix, part 13: derivations",
- href: "https://ianthehenry.com/posts/how-to-learn-nix/derivations",
- source: {
- title: "Ian Henry's blog",
- href: "https://ianthehenry.com/posts/how-to-learn-nix"
- }
- },
- {
- title: "Our first derivation",
- href: "https://nixos.org/guides/nix-pills/our-first-derivation",
- source: {
- title: "Nix Pills",
- href: "https://nixos.org/guides/nix-pills"
- }
- }
-]
+externalSources:
+ [
+ {
+ title: "Derivations",
+ href: "https://nixos.org/manual/nix/stable/language/derivations",
+ source:
+ {
+ title: "The Nix manual",
+ href: "https://nixos.org/manual/nix/stable",
+ },
+ },
+ {
+ title: "How to learn Nix, part 13: derivations",
+ href: "https://ianthehenry.com/posts/how-to-learn-nix/derivations",
+ source:
+ {
+ title: "Ian Henry's blog",
+ href: "https://ianthehenry.com/posts/how-to-learn-nix",
+ },
+ },
+ {
+ title: "Our first derivation",
+ href: "https://nixos.org/guides/nix-pills/our-first-derivation",
+ source:
+ { title: "Nix Pills", href: "https://nixos.org/guides/nix-pills" },
+ },
+ ]
---
-A *derivation* is an instruction that Nix uses to [*realise*][realisation] a Nix package.
+A _derivation_ is an instruction that Nix uses to [_realise_][realisation] a Nix package.
They're created using a special `derivation` function in the [Nix language](#nix-language).
They can depend on any number of other derivations and produce one or more final [outputs](#outputs).
A derivation and all of the dependencies required to build it—direct dependencies, and all dependencies of those dependencies, etc—is called a [closure].
@@ -46,10 +47,11 @@ The most common outputs:
- `dev`, general development resources such as header files
- `man`, for manual pages
-A derivation and all of the dependencies required to build it—direct dependencies, and all dependencies of those dependencies, etc—is called a *package closure*.
+A derivation and all of the dependencies required to build it—direct dependencies, and all dependencies of those dependencies, etc—is called a _package closure_.
-
-You may find it helpful to think of a derivation as the *plan* or *blueprint* for a Nix package.
+
+ You may find it helpful to think of a derivation as the *plan* or *blueprint*
+ for a Nix package.
## Derivations in the Nix language \{#nix-language}
@@ -57,7 +59,7 @@ You may find it helpful to think of a derivation as the *plan* or *blueprint* fo
In the [Nix language][lang], derivations are created using the [`derivation`][func] function.
Here's the type signature for `derivation` expressed as a [Haskell]-ish signature:[^1]
-```haskell
+```haskell title="Derivation type signature" disableClipboard
derivation ::
{ system : String
, name : String
@@ -69,7 +71,7 @@ derivation ::
Here's an example derivation:
-```nix
+```nix title="Example derivation"
derivation {
# A name for the derivation (whatever you choose)
name = "hello-text";
@@ -90,10 +92,12 @@ But derivations can be far less straightforward, because the scripting logic tha
If Nix sees this string...
-```nix
-buildPhase = ''
- mv ${pkgs.website}/favicon.ico
-'';
+```nix title="my-file.nix"
+{
+ buildPhase = ''
+ mv ${pkgs.website}/favicon.ico
+ '';
+}
```
The string output of a derivation is always a [Nix store path][store]
@@ -113,7 +117,7 @@ There are two special variables to be aware of when writing derivations:
Most derivations in the Nix ecosystem are based on the [`mkDerivation`][mk] function from the [standard environment][stdenv].
-While you *can* create derivations using the raw `derivation` function, it's far more common to use a wrapper function around it.
+While you _can_ create derivations using the raw `derivation` function, it's far more common to use a wrapper function around it.
Perhaps the most commonly used wrapper function is [`stdenv.mkDerivation`][mk].
Arguments:
diff --git a/src/content/concepts/dev-env.mdx b/src/content/concepts/dev-env.mdx
new file mode 100644
index 00000000..5dc9f3f9
--- /dev/null
+++ b/src/content/concepts/dev-env.mdx
@@ -0,0 +1,39 @@
+---
+title: Development environments
+wip: true
+snippet: |
+ Hermetically sealed environments that you can define using the [Nix language](/concepts/nix-language)
+related: ["flakes"]
+externalSources:
+ [
+ {
+ title: "Declarative and reproducible developer environments",
+ href: "https://nix.dev/tutorials/declarative-and-reproducible-developer-environments",
+ source: { title: "nix.dev", href: "https://nix.dev" },
+ },
+ {
+ title: "Set up a development environment",
+ href: "https://nix.dev/tutorials/dev-environment",
+ source: { title: "nix.dev", href: "https://nix.dev" },
+ },
+ {
+ title: "Throwaway development environments with Nix",
+ href: "https://monospacedmonologues.com/2022/06/throwaway-development-environments-with-nix",
+ source:
+ {
+ title: "Monospaced Monologues",
+ href: "https://monospacedmonologues.com",
+ },
+ },
+ ]
+---
+
+A Nix _development environment_ is a derivation which builds a shell system environment.
+This environment is [hermetically] sealed off from the host,
+which means that no other dev environment can make changes or override tooling in it.
+
+This enables you to contain all development tooling (the environment [closure]) for a particular project in a dev shell,
+which is separated from even the dev shells for projects of a similar nature (same programming language, same set of dependencies, etc).
+
+[hermetically]: /concepts/hermeticity
+[closure]: /concepts/closures
diff --git a/src/pages/concepts/ecosystem.mdx b/src/content/concepts/ecosystem.mdx
similarity index 71%
rename from src/pages/concepts/ecosystem.mdx
rename to src/content/concepts/ecosystem.mdx
index ed8a49f0..34c85cb0 100644
--- a/src/pages/concepts/ecosystem.mdx
+++ b/src/content/concepts/ecosystem.mdx
@@ -4,27 +4,26 @@ wip: true
snippet: |
The vast constellation of projects surrounding, built on, and inspired by [Nix](/concepts/nix)
related: ["declarative", "nix", "nixos", "nixpkgs", "reproducibility"]
-externalSources: [
- {
- title: "Nix ecosystem",
- href: "https://wiki.nixos.org/wiki/Nix_Ecosystem",
- source: {
- title: "The NixOS wiki",
- href: "https://wiki.nixos.org"
- }
- },
- {
- title: "How to change the Nix ecosystem to become mainstream",
- href: "https://www.youtube.com/watch?v=Q0-0I0jKVwg",
- source: {
- title: "NixCon 2020 talk by Domen Kožar",
- href: "https://cfp.nixcon.org/nixcon2020/talk/RKPT7U"
- }
- }
-]
+externalSources:
+ [
+ {
+ title: "Nix ecosystem",
+ href: "https://wiki.nixos.org/wiki/Nix_Ecosystem",
+ source: { title: "The NixOS wiki", href: "https://wiki.nixos.org" },
+ },
+ {
+ title: "How to change the Nix ecosystem to become mainstream",
+ href: "https://www.youtube.com/watch?v=Q0-0I0jKVwg",
+ source:
+ {
+ title: "NixCon 2020 talk by Domen Kožar",
+ href: "https://cfp.nixcon.org/nixcon2020/talk/RKPT7U",
+ },
+ },
+ ]
---
-The *Nix ecosystem* is a software ecosystem that has the [Nix] package manager and [language] at its core but also includes a vast network of related tools and systems built on top of Nix.
+The _Nix ecosystem_ is a software ecosystem that has the [Nix] package manager and [language] at its core but also includes a vast network of related tools and systems built on top of Nix.
On the official side, the Nix ecosystem includes [NixOS], [NixOps], [Hydra], [Home Manager][hm], and [other projects][others].
On the unofficial side, the Nix ecosystem includes everything from [language] libraries and helpers to [package repositories][packages] to developer tools and far beyond.
@@ -32,7 +31,6 @@ Depending on your perspective, Nix-inspired projects like [GNU Guix][guix] and p
Regardless of where you draw the lines, getting into Nix can bring vast regions of the software industry into your reach.
-
[declarative]: /concepts/declarative
[guix]: http://guix.gnu.org
[hm]: https://github.com/nix-community/home-manager
diff --git a/src/pages/concepts/flakehub.mdx b/src/content/concepts/flakehub.mdx
similarity index 63%
rename from src/pages/concepts/flakehub.mdx
rename to src/content/concepts/flakehub.mdx
index 9026e382..8f3cb538 100644
--- a/src/pages/concepts/flakehub.mdx
+++ b/src/content/concepts/flakehub.mdx
@@ -3,52 +3,53 @@ title: FlakeHub
snippet: |
A service that does fun stuff
related: ["ecosystem", "flakes", "pinning"]
-externalSources: [
- {
- title: "FlakeHub documentation",
- href: "https://flakehub.com/docs",
- source: {
- title: "FlakeHub",
- href: "https://flakehub.com"
- }
- },
- {
- title: "Introducing FlakeHub",
- href: "https://determinate.systems/posts/introducing-flakehub",
- source: {
- title: "The Determinate Systems blog",
- href: "https://determinate.systems/posts"
- }
- },
- {
- title: "`fh`: the CLI for FlakeHub",
- href: "https://determinate.systems/posts/flakehub-cli",
- source: {
- title: "The Determinate Systems blog",
- href: "https://determinate.systems/posts"
- }
- }
-]
+externalSources:
+ [
+ {
+ title: "FlakeHub documentation",
+ href: "https://flakehub.com/docs",
+ source: { title: "FlakeHub", href: "https://flakehub.com" },
+ },
+ {
+ title: "Introducing FlakeHub",
+ href: "https://determinate.systems/posts/introducing-flakehub",
+ source:
+ {
+ title: "The Determinate Systems blog",
+ href: "https://determinate.systems/posts",
+ },
+ },
+ {
+ title: "`fh`: the CLI for FlakeHub",
+ href: "https://determinate.systems/posts/flakehub-cli",
+ source:
+ {
+ title: "The Determinate Systems blog",
+ href: "https://determinate.systems/posts",
+ },
+ },
+ ]
---
[FlakeHub] is a platform for discovering and publishing [Nix flakes][flakes] built by [Determinate Systems][detsys].
It offers a wide variety of features that Nix on its own does not:
-* [Semantic versioning][semver] for flakes, including version modifiers like `~` (flexible patch) and `=` (exact match).
-* The ability to explore the Nix flake landscape in a variety of ways:
- * Plaintext search
- * [All flakes][all-flakes]
- * [All organizations][all-orgs]
- * Via labels such as [`nixos`][label-nixos] or [`rust`][label-rust]
-* Automated flake [publishing] with GitHub Actions, including a user-friendly [wizard] to help you construct an Actions configuration for your project.
+- [Semantic versioning][semver] for flakes, including version modifiers like `~` (flexible patch) and `=` (exact match).
+- The ability to explore the Nix flake landscape in a variety of ways:
+ - Plaintext search
+ - [All flakes][all-flakes]
+ - [All organizations][all-orgs]
+ - Via labels such as [`nixos`][label-nixos] or [`rust`][label-rust]
+- Automated flake [publishing] with GitHub Actions, including a user-friendly [wizard] to help you construct an Actions configuration for your project.
FlakeHub also offers a CLI tool called [`fh`][fh] that you can use to perform a variety of actions against the FlakeHub API.
-
+
Although we at [Determinate Systems][detsys] believe that FlakeHub makes important aspects of using [Nix flakes][flakes] more straightforward—and fun!—it is a proprietary platform and mostly not open source.
Most of FlakeHub's features are free, including [semantic versioning][semver] and publishing [public flakes][visibility]
In other words, you can use [Nix] and [Nix flakes][flakes] without using FlakeHub just as you can use [Git] without using [GitHub].
+
[all-flakes]: https://flakehub.com/flakes
diff --git a/src/pages/concepts/flakes.mdx b/src/content/concepts/flakes.mdx
similarity index 83%
rename from src/pages/concepts/flakes.mdx
rename to src/content/concepts/flakes.mdx
index 53fefc4c..10da9e24 100644
--- a/src/pages/concepts/flakes.mdx
+++ b/src/content/concepts/flakes.mdx
@@ -4,54 +4,44 @@ wip: true
snippet: |
A system for referencing and sharing [Nix code](/concepts/nix-language)
related: ["channels"]
-externalSources: [
- {
- title: "Flakes",
- href: "https://wiki.nixos.org/wiki/Flakes",
- source: {
- title: "The NixOS wiki",
- href: "https://wiki.nixos.org"
- }
- },
- {
- title: "Practical Nix flakes",
- href: "https://serokell.io/blog/practical-nix-flakes",
- source: {
- title: "The Serokell blog",
- href: "https://serokell.io/blog"
- }
- },
- {
- title: "Nix flakes: an introduction",
- href: "https://xeiaso.net/blog/nix-flakes-1-2022-02-21",
- source: {
- title: "Xe Iaso's blog",
- href: "https://xeiaso.net/blog"
- }
- },
- {
- title: "Nix flakes are your friend",
- href: "https://www.youtube.com/watch?v=L-xORCdL3FI",
- source: {
- title: "YouTube",
- href: "https://youtube.com"
- }
- }
-]
+externalSources:
+ [
+ {
+ title: "Flakes",
+ href: "https://wiki.nixos.org/wiki/Flakes",
+ source: { title: "The NixOS wiki", href: "https://wiki.nixos.org" },
+ },
+ {
+ title: "Practical Nix flakes",
+ href: "https://serokell.io/blog/practical-nix-flakes",
+ source: { title: "The Serokell blog", href: "https://serokell.io/blog" },
+ },
+ {
+ title: "Nix flakes: an introduction",
+ href: "https://xeiaso.net/blog/nix-flakes-1-2022-02-21",
+ source: { title: "Xe Iaso's blog", href: "https://xeiaso.net/blog" },
+ },
+ {
+ title: "Nix flakes are your friend",
+ href: "https://www.youtube.com/watch?v=L-xORCdL3FI",
+ source: { title: "YouTube", href: "https://youtube.com" },
+ },
+ ]
---
-
+
Nix flakes are currently an **experimental feature** in Nix and there is currently no specific timeline for making flakes official.
While the user interface around flakes is unlikely to change drastically while they remain experimental, there may be breaking changes along the way.
[Channels] will continue be the "official" way of using Nix for the foreseeable future.
We strongly recommend, however, that you learn to use flakes if you're already a Nix user or to begin your Nix journey with flakes rather than channels if you're just getting started with Nix.
+
-A Nix *flake* is a directory with a `flake.nix` and [`flake.lock`](#lockfile) at the root that [outputs](#outputs) Nix expressions that others can use to do things like [build packages][packages], [run programs][run], use [development environments][env], or stand up [NixOS] systems.
+A Nix _flake_ is a directory with a `flake.nix` and [`flake.lock`](#lockfile) at the root that [outputs](#outputs) Nix expressions that others can use to do things like [build packages][packages], [run programs][run], use [development environments][env], or stand up [NixOS] systems.
If necessary, flakes can use the outputs of other flakes as [inputs](#inputs).
-
+
It may be helpful to think of flakes as processors of [Nix code][lang].
They take Nix expressions as [input](#inputs) and [output](#outputs) things that Nix can use, like [package definitions][packages], [development environments][env], or [NixOS] configurations.
@@ -60,11 +50,12 @@ Let's say that I create a flake that uses a helper function output by [Nixpkgs]&
My teammate could then use the package definition from my flake as part of a Nix development environment.
Another team then could use that development environment in one of their projects.
And so on.
+
## Flake references \{#references}
-A *flake reference* is a string representation of where the flake is located.
+A _flake reference_ is a string representation of where the flake is located.
Flake references are used in two places:
1. In flake [input declarations](#inputs) to depend on outputs from the flake.
@@ -87,19 +78,19 @@ You can find a more systematic treatment of flake references in the [official do
### References and revisions \{#revisions}
-Flake references are *always* to a specific revision of the flake.
+Flake references are _always_ to a specific revision of the flake.
[Nixpkgs], for example, is a flake but each revision of Nixpkgs—and there are many thousands—has a flake reference.
## Flake inputs \{#inputs}
-*Flake inputs* are Nix dependencies that a flake needs to be built.
+_Flake inputs_ are Nix dependencies that a flake needs to be built.
Each input in the set can be pulled from various sources, such as github, generic git repositories, and even your filesystem.
Furthermore, inputs can modify each other's inputs to make sure that,
for example, multiple dependencies all rely on the same version of nixpkgs.
This is done via the `inputs..follows` attribute.
-```nix filename=flake.nix
+```nix title="flake.nix"
{
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs";
@@ -120,7 +111,7 @@ Any Nix CLI command that is run against the flake—like `nix build`, `nix d
Here's an example section of a `flake.lock` file that pins [Nixpkgs] to a specific revision:
-```json filename=flake.lock
+```json title="flake.lock"
{
"nodes": {
"nixpkgs": {
@@ -137,7 +128,7 @@ Here's an example section of a `flake.lock` file that pins [Nixpkgs] to a specif
// The type of input
"type": "github"
}
- },
+ }
// Other inputs
}
}
@@ -145,7 +136,7 @@ Here's an example section of a `flake.lock` file that pins [Nixpkgs] to a specif
If this `flake.lock` were alongside a `flake.nix` with this [input block](#inputs)...
-```nix filename=flake.nix
+```nix title="flake.nix"
{
inputs = {
nixpkgs.url = "nixpkgs";
@@ -161,22 +152,22 @@ If this `flake.lock` were alongside a `flake.nix` with this [input block](#input
### Flake registries \{#registries}
-[*Flake registries*][registry-official] are a convenience feature that enables you to refer to flakes using symbolic identifiers rather than full flake references.
+[_Flake registries_][registry-official] are a convenience feature that enables you to refer to flakes using symbolic identifiers rather than full flake references.
The most widely used symbolic identifier is `nixpkgs`, which is an alias for the `github:NixOS/nixpkgs/nixpkgs-unstable` flake [reference](#references)
Some symbolic identifiers that you may encounter:
-Symbolic identifier | Full flake reference
-:------------------|:-------------------
-[`nixpkgs`][nixpkgs] | `github:NixOS/nixpkgs/nixpkgs-unstable`
-[`flake-utils`][flake-utils] | `github:numtide/flake-utils`
-[`home-manager`][hm] | `github:nix-community/home-manager`
+| Symbolic identifier | Full flake reference |
+| :--------------------------- | :-------------------------------------- |
+| [`nixpkgs`][nixpkgs] | `github:NixOS/nixpkgs/nixpkgs-unstable` |
+| [`flake-utils`][flake-utils] | `github:numtide/flake-utils` |
+| [`home-manager`][hm] | `github:nix-community/home-manager` |
The full default global flake registry is kept as a [JSON file][registry-json].
Here's an example flake that uses symbolic identifiers:
-```nix filename=flake.nix
+```nix title="flake.nix"
{
outputs = { self, nixpkgs, flake-utils }:
let
@@ -194,13 +185,13 @@ Using flake registries is always optional.
## Flake outputs \{#outputs}
-*Flake outputs* are what a flake produces as part of its build.
+_Flake outputs_ are what a flake produces as part of its build.
Each flake can have many different outputs simultaneously, including but not limited to:
-* [Nix packages][packages]
-* [Nix development environments][env]
-* [NixOS] configurations
-* [Nix templates](#templates)
+- [Nix packages][packages]
+- [Nix development environments][env]
+- [NixOS] configurations
+- [Nix templates](#templates)
Flake outputs are defined by a function, which takes an attribute set as input, containing each of the inputs to that flake (named after the chosen identifier in the [inputs](#inputs) section).
@@ -209,14 +200,15 @@ Flake outputs are defined by a function, which takes an attribute set as input,
In addition to things like packages and NixOS configurations, flakes can also output Nix [functions] for use elsewhere.
[Nixpkgs], for example, outputs many helper functions via the `lib` attribute.
-
-The convention of using `lib` to output functions is observed not just by Nixpkgs but by many other Nix projects.
-You're free, however, to output functions via whichever attribute you prefer.
+
+ The convention of using `lib` to output functions is observed not just by
+ Nixpkgs but by many other Nix projects. You're free, however, to output
+ functions via whichever attribute you prefer.
Here's an example flake that outputs a `sayHello` function, via the `lib` attribute, that takes a name as an input and outputs a string saying hello to a person with that name:
-```nix filename=flake.nix
+```nix title="flake.nix"
{
outputs = { self }: {
lib = {
@@ -233,7 +225,7 @@ Another Nix flake could then specify this flake as an [input](#inputs) and use `
Some flake outputs need to be [system specific][specificity], including [packages], [development environments][env], and [NixOS] configurations.
Here's an example flake that outputs a package that can be used by `x86_64-linux` systems (64-bit AMD/Intel Linux):
-```nix filename=flake.nix
+```nix title="flake.nix"
{
outputs = { self, nixpkgs }: let
# Declare the system
@@ -251,7 +243,7 @@ In many cases, however, you'll need to output things like [packages] or [develop
Helper libraries like [`flake-utils`][flake-utils] provide convenient mechanisms for doing that.
You can also use Nix functions like this:
-```nix filename=flake.nix
+```nix title="flake.nix"
{
outputs = { self, nixpkgs }: let
# The set of systems to provide outputs for
@@ -273,12 +265,12 @@ You can also use Nix functions like this:
## Flake templates \{#templates}
-[*Flake templates*][init] enable you to either initialize a new Nix project with pre-supplied content or add a set of files to an existing project.
+[_Flake templates_][init] enable you to either initialize a new Nix project with pre-supplied content or add a set of files to an existing project.
You can initialize a flake template using the [`nix flake init`][init] command.
Flakes can [output](#outputs) templates using the `templates` attribute.
Here's an example:
-```nix filename=flake.nix
+```nix title="flake.nix"
{
outputs = { self }: {
templates = {
diff --git a/src/pages/concepts/hermeticity.mdx b/src/content/concepts/hermeticity.mdx
similarity index 68%
rename from src/pages/concepts/hermeticity.mdx
rename to src/content/concepts/hermeticity.mdx
index e0f984d0..2c74ae48 100644
--- a/src/pages/concepts/hermeticity.mdx
+++ b/src/content/concepts/hermeticity.mdx
@@ -4,22 +4,19 @@ wip: true
snippet: |
Isolating build environments from the host to guarantee [reproducible](/concepts/reproducibility) builds
related: ["dev-env"]
-externalSources: [
- {
- title: "Hermeticity",
- href: "https://bazel.build/basics/hermeticity",
- source: {
- title: "The Bazel documentation",
- href: "https://bazel.build"
- }
- }
-]
+externalSources:
+ [
+ {
+ title: "Hermeticity",
+ href: "https://bazel.build/basics/hermeticity",
+ source: { title: "The Bazel documentation", href: "https://bazel.build" },
+ },
+ ]
---
-*Hermeticity* is a property of Nix builds, which isolates them from the host system via various mechanisms.
+_Hermeticity_ is a property of Nix builds, which isolates them from the host system via various mechanisms.
This results in a system where the same set of source inputs will always map to the same build outputs,
because changes on the host can not affect a build.
Any system which is not hermetic is called "impure", implying that changes outside of the input set can have an impact on the build result.
This is the inverse of Nix's "purity" property.
-
diff --git a/src/pages/concepts/incremental-builds.mdx b/src/content/concepts/incremental-builds.mdx
similarity index 82%
rename from src/pages/concepts/incremental-builds.mdx
rename to src/content/concepts/incremental-builds.mdx
index 93fec077..b7a272ae 100644
--- a/src/pages/concepts/incremental-builds.mdx
+++ b/src/content/concepts/incremental-builds.mdx
@@ -4,19 +4,17 @@ wip: true
snippet: |
Package builds that cut out unnecessary steps (and thus unnecessary build resources and time)
related: ["caching", "realisation", "nix-store"]
-externalSources: [
- {
- title: "Incremental build model",
- href: "https://en.wikipedia.org/wiki/Incremental_build_model",
- source: {
- title: "Wikipedia",
- href: "https://wikipedia.org"
- }
- }
-]
+externalSources:
+ [
+ {
+ title: "Incremental build model",
+ href: "https://en.wikipedia.org/wiki/Incremental_build_model",
+ source: { title: "Wikipedia", href: "https://wikipedia.org" },
+ },
+ ]
---
-*Incremental builds* are build processes that don't need to build the entire dependency tree of a software artifact every time because they use mechanisms like intelligent [caching] to avoid rebuilding artifacts that are already available.
+_Incremental builds_ are build processes that don't need to build the entire dependency tree of a software artifact every time because they use mechanisms like intelligent [caching] to avoid rebuilding artifacts that are already available.
Nix is one of several available build systems that offers incremental builds.
## How Nix provides incremental builds \{#how}
@@ -30,12 +28,16 @@ Whenever Nix builds a [package][packages], it builds the entire [closure], or de
The hash portion enables Nix to "know" what doesn't need to be built.
If the package `super-important-dependency` is necessary to build the package `final-production-artifact`, Nix can inspect the [derivation] for `super-important-dependency` and calculate a hash for that dependency and, thus, a Nix store path for it, something like this:
-
+
With that information in hand, Nix can then check to see if one of these places already has the artifact:
-* The local [Nix store][store]
-* One of your configured [binary caches][binary] (if any)
+- The local [Nix store][store]
+- One of your configured [binary caches][binary] (if any)
Nix builds a given derivation only if it fails to discover a realised artifact in one of these places.
This can make a huge difference when building large [closures][closure].
diff --git a/src/pages/concepts/nix-installer.mdx b/src/content/concepts/nix-installer.mdx
similarity index 68%
rename from src/pages/concepts/nix-installer.mdx
rename to src/content/concepts/nix-installer.mdx
index c65d9e58..7c532100 100644
--- a/src/pages/concepts/nix-installer.mdx
+++ b/src/content/concepts/nix-installer.mdx
@@ -4,32 +4,27 @@ wip: true
snippet: |
A fast, stable [Nix](/concepts/nix) installer created by [Determinate Systems](https://determinate.systems)
related: ["flakes"]
-externalSources: [
- {
- title: "The Determinate Nix Installer repo",
- href: "https://github.com/DeterminateSystems/nix-installer",
- source: {
- title: "GitHub",
- href: "https://github.com"
- }
- },
- {
- title: "Rust",
- href: "https://rust-lang.org"
- }
-]
+externalSources:
+ [
+ {
+ title: "The Determinate Nix Installer repo",
+ href: "https://github.com/DeterminateSystems/nix-installer",
+ source: { title: "GitHub", href: "https://github.com" },
+ },
+ { title: "Rust", href: "https://rust-lang.org" },
+ ]
---
The [Determinate Nix Installer][install] is a fast and stable Nix installer created by [Determinate Systems][ds].
It currently supports both Linux and macOS.
-
+{/* */}
## Using the Determinate Nix Installer \{#using}
You can run the installer on your system using this command:
-```shell
+```shell title="One command to install Nix"
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
```
diff --git a/src/pages/concepts/nix-language.mdx b/src/content/concepts/nix-language.mdx
similarity index 61%
rename from src/pages/concepts/nix-language.mdx
rename to src/content/concepts/nix-language.mdx
index fe9a5c6f..32290d3e 100644
--- a/src/pages/concepts/nix-language.mdx
+++ b/src/content/concepts/nix-language.mdx
@@ -4,60 +4,51 @@ wip: true
snippet: |
The language you use to define Nix [package builds](/concepts/packages), [development environments](/concepts/dev-env), [NixOS configurations](/concepts/nixos), and more.
related: ["declarative", "nix", "nixos", "nixpkgs"]
-externalSources: [
- {
- title: "Nix language basics",
- href: "https://nix.dev/tutorials/nix-language",
- source: {
- title: "nix.dev",
- href: "https://nix.dev"
- }
- },
- {
- title: "Overview of the Nix language",
- href: "https://wiki.nixos.org/wiki/Overview_of_the_Nix_Language",
- source: {
- title: "The NixOS wiki",
- href: "https://wiki.nixos.org"
- }
- },
- {
- title: "Nix language",
- href: "https://nixos.org/manual/nix/stable/language",
- source: {
- title: "The Nix manual",
- href: "https://nixos.org/manual/nix/stable"
- }
- },
- {
- title: "Learn nix in Y minutes",
- href: "https://learnxinyminutes.com/docs/nix",
- source: {
- title: "Learn X in Y minutes",
- href: "https://learnxinyminutes.com"
- }
- },
- {
- title: "Nix: a one pager",
- href: "https://github.com/tazjin/nix-1p",
- source: {
- title: "GitHub",
- href: "https://github.com"
- }
- }
-]
+externalSources:
+ [
+ {
+ title: "Nix language basics",
+ href: "https://nix.dev/tutorials/nix-language",
+ source: { title: "nix.dev", href: "https://nix.dev" },
+ },
+ {
+ title: "Overview of the Nix language",
+ href: "https://wiki.nixos.org/wiki/Overview_of_the_Nix_Language",
+ source: { title: "The NixOS wiki", href: "https://wiki.nixos.org" },
+ },
+ {
+ title: "Nix language",
+ href: "https://nixos.org/manual/nix/stable/language",
+ source:
+ {
+ title: "The Nix manual",
+ href: "https://nixos.org/manual/nix/stable",
+ },
+ },
+ {
+ title: "Learn nix in Y minutes",
+ href: "https://learnxinyminutes.com/docs/nix",
+ source:
+ { title: "Learn X in Y minutes", href: "https://learnxinyminutes.com" },
+ },
+ {
+ title: "Nix: a one pager",
+ href: "https://github.com/tazjin/nix-1p",
+ source: { title: "GitHub", href: "https://github.com" },
+ },
+ ]
---
-Nix is the *programming language* that powers the Nix *packaging system*.
+Nix is the _programming language_ that powers the Nix _packaging system_.
## Why a programming language?
-You might ask yourself why Nix even *needs* a programming language.
+You might ask yourself why Nix even _needs_ a programming language.
Why can't packages be declared via some JSON, YAML, or TOML schema?
The problem with that lies in the dynamic nature of how Nix configures packages and allows them to be combined.
-Nix as a *programming language* can be thought of as a kind of "JSON, but with functions".
+Nix as a _programming language_ can be thought of as a kind of "JSON, but with functions".
All statements are [declarative], meaning that there's no sequential flow of instructions that makes up a Nix package.
-Instead functions are called that assign values to fields in *attribute sets*, which in turn may get assigned to other values.
+Instead functions are called that assign values to fields in _attribute sets_, which in turn may get assigned to other values.
## How does Nix work?
@@ -65,23 +56,22 @@ Nix uses a few important characteristics in programming language design to work.
Some of these terms can seem daunting, when you're not already familiar with what they mean and how they work with each other.
So first, let's cover these principles:
-*Nix* is a pure, functional, lazy, declarative, and reproducible programming language.
+_Nix_ is a pure, functional, lazy, declarative, and reproducible programming language.
| Concept | Description |
-|-------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|
-| Pure | A programming-language design concept by which functions can not cause *side effects*. The only result is the one a function returns |
-| Functional | A programming-language design concept by which *functions* can be passed as function arguments, and returned as results |
+| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| Pure | A programming-language design concept by which functions can not cause _side effects_. The only result is the one a function returns |
+| Functional | A programming-language design concept by which _functions_ can be passed as function arguments, and returned as results |
| Lazy | A programming-language design concept by which functions and data collections are not evaluated until they are needed to complete a computation |
-| Declarative | Describing a system outcome, instead of instructing the computer *how* to achieve the outcome |
-| [Reproducible](/concepts/reproducibility) | An operation that is performed twice yields the same result. The same inputs map to the same outputs |
-
+| Declarative | Describing a system outcome, instead of instructing the computer _how_ to achieve the outcome |
+| [Reproducible](/concepts/reproducibility) | An operation that is performed twice yields the same result. The same inputs map to the same outputs |
## Syntax basics
-As mentioned previously, Nix uses *assignments* to compute and process data for packages, modules, and other utilities.
+As mentioned previously, Nix uses _assignments_ to compute and process data for packages, modules, and other utilities.
The code below, for example, calls a function called `my_function` with the parameters `2` and `3`, and assigns its output to the `my_value` field.
-```nix
+```nix title="Assignments"
{
my_value = my_function 2 3;
}
@@ -89,7 +79,7 @@ The code below, for example, calls a function called `my_function` with the para
Functions are defined using this syntax, where `x` and `y` are attributes passed into the function:
-```nix
+```nix title="Functions"
{
my_function = x: y: x + y;
}
@@ -99,11 +89,11 @@ The body of the function automatically returns the result of the function.
As you can see in the example above, functions are called by spaces between it and its parameters.
No commas are needed to separate parameters.
-The two most common data structures are *attribute sets* and *lists*.
+The two most common data structures are _attribute sets_ and _lists_.
Attribute sets are key-value stores.
Lists can contain different types of values and don't need to be comma separated.
-```nix
+```nix title="Recursive attributes"
rec {
number_key = 5;
list_key = [ number_key true "Hello" ];
diff --git a/src/pages/concepts/nix-store.mdx b/src/content/concepts/nix-store.mdx
similarity index 71%
rename from src/pages/concepts/nix-store.mdx
rename to src/content/concepts/nix-store.mdx
index 8fa019d2..a772fe86 100644
--- a/src/pages/concepts/nix-store.mdx
+++ b/src/content/concepts/nix-store.mdx
@@ -4,27 +4,30 @@ wip: true
snippet: |
An on-disk storage system used by [Nix](/concepts/nix) to build, store, and cache [packages](/concepts/packages) and other artifacts
related: ["caching", "derivations", "nix-language", "packages"]
-externalSources: [
- {
- title: "What is Nix?",
- href: "https://shopify.engineering/what-is-nix",
- source: {
- title: "The Shopify engineering blog",
- href: "https://shopify.engineering"
- }
- },
- {
- title: "Exploring the Nix store internals",
- href: "https://youtube.com/watch?v=foN0PfdRlNI",
- source: {
- title: "Tweag's YouTube channel",
- href: "https://youtube.com/@tweag"
- }
- }
-]
+externalSources:
+ [
+ {
+ title: "What is Nix?",
+ href: "https://shopify.engineering/what-is-nix",
+ source:
+ {
+ title: "The Shopify engineering blog",
+ href: "https://shopify.engineering",
+ },
+ },
+ {
+ title: "Exploring the Nix store internals",
+ href: "https://youtube.com/watch?v=foN0PfdRlNI",
+ source:
+ {
+ title: "Tweag's YouTube channel",
+ href: "https://youtube.com/@tweag",
+ },
+ },
+ ]
---
-The *Nix store* is a storage system in your filesystem with its root at `/nix/store` by default.
+The _Nix store_ is a storage system in your filesystem with its root at `/nix/store` by default.
The Nix daemon stores several things in the Nix store:
- [Derivations]: stand-alone files suffixed with `.drv` such as `/nix/store/-my-package.drv`
@@ -46,7 +49,7 @@ Let's break store paths down into their constituent elements:
Some important things to note about store paths in Nix:
- The root path at `/nix/store` doesn't conflict with other standard system paths like `/usr/bin`.
-- The hash ensures that two packages with the same name have completely different paths if the inputs to the package differ *at all*. If you were to change one letter in one file in the inputs to `my-package-1.0`, for example, you may end up with a store path like `/nix/store/1aq3wchnvv7yn0d6y1r3j129hjqmv2k3-my-package-1.0`.
+- The hash ensures that two packages with the same name have completely different paths if the inputs to the package differ _at all_. If you were to change one letter in one file in the inputs to `my-package-1.0`, for example, you may end up with a store path like `/nix/store/1aq3wchnvv7yn0d6y1r3j129hjqmv2k3-my-package-1.0`.
- Package names are fundamentally arbitrary. You can provide whatever naming conventions you wish. If you don't want your packages to have a concept of version, you can name them `my-package` and distinguish based on the input hash.
[derivations]: /concepts/derivations
diff --git a/src/pages/concepts/nix.mdx b/src/content/concepts/nix.mdx
similarity index 71%
rename from src/pages/concepts/nix.mdx
rename to src/content/concepts/nix.mdx
index 68a88eeb..fb3030aa 100644
--- a/src/pages/concepts/nix.mdx
+++ b/src/content/concepts/nix.mdx
@@ -4,44 +4,34 @@ wip: true
snippet: |
A CLI, [package manager](/concepts/package-management), and [programming language](/concepts/nix-language)
related: ["nix-language", "nixos", "nixpkgs"]
-externalSources: [
- {
- title: "The official Nix website",
- href: "https://nixos.org"
- },
- {
- title: "Nix package manager",
- href: "https://wiki.nixos.org/wiki/Nix_package_manager",
- source: {
- title: "The NixOS wiki",
- href: "https://wiki.nixos.org"
- }
- },
- {
- title: "The Nix repository",
- href: "https://github.com/NixOS/nix",
- source: {
- title: "GitHub",
- href: "https://github.com"
- }
- },
- {
- title: "What is Nix?",
- href: "https://shopify.engineering/what-is-nix",
- source: {
- title: "The Shopify engineering blog",
- href: "https://shopify.engineering"
- }
- },
- {
- title: "Nix (package manager)",
- href: "https://en.wikipedia.org/wiki/Nix_(package_manager)",
- source: {
- title: "Wikipedia",
- href: "https://wikipedia.org"
- }
- }
-]
+externalSources:
+ [
+ { title: "The official Nix website", href: "https://nixos.org" },
+ {
+ title: "Nix package manager",
+ href: "https://wiki.nixos.org/wiki/Nix_package_manager",
+ source: { title: "The NixOS wiki", href: "https://wiki.nixos.org" },
+ },
+ {
+ title: "The Nix repository",
+ href: "https://github.com/NixOS/nix",
+ source: { title: "GitHub", href: "https://github.com" },
+ },
+ {
+ title: "What is Nix?",
+ href: "https://shopify.engineering/what-is-nix",
+ source:
+ {
+ title: "The Shopify engineering blog",
+ href: "https://shopify.engineering",
+ },
+ },
+ {
+ title: "Nix (package manager)",
+ href: "https://en.wikipedia.org/wiki/Nix_(package_manager)",
+ source: { title: "Wikipedia", href: "https://wikipedia.org" },
+ },
+ ]
---
[*Nix*][nix] can be a somewhat confusing term because it refers to multiple things:
@@ -53,7 +43,7 @@ externalSources: [
All of these are closely interrelated and should be thought of as a single tool.
In this document, we'll go over each of these three aspects of Nix.
-
+
The Nix project is fully open source and largely developed within the [`NixOS`][nixos-org] organization on [GitHub].
It's licensed under [LGPL 2.1][license], which is generally quite permissive regarding commercial use.
@@ -65,21 +55,21 @@ We have also created [Determinate Nix][det-nix], a downstream distribution of Ni
There are two different Nix CLIs currently active:
-* The [unified Nix CLI](#unified-cli) is currently experimental but, from the standpoint of [Determinate Systems][ds], recommended for using Nix.
+- The [unified Nix CLI](#unified-cli) is currently experimental but, from the standpoint of [Determinate Systems][ds], recommended for using Nix.
It wraps all Nix functionality into a single `nix` executable and supports [flakes]
-* The [original Nix CLI](#original-cli), which is currently standard but, from the standpoint of [Determinate Systems][ds], *not* recommended for using Nix.
+- The [original Nix CLI](#original-cli), which is currently standard but, from the standpoint of [Determinate Systems][ds], _not_ recommended for using Nix.
### The unified CLI \{#unified-cli}
-The *unified CLI* is a still-experimental way of using Nix that involves just one executable called `nix`.
-*All* Nix functionality is wrapped into this tool, including commands like `nix build` for building [packages] instead of the old `nix-build` tool, `nix develop` for activating Nix [development environments][env] instead of the old `nix-shell` tool, `nix store` for managing the [Nix store][store] instead of the old `nix-store` tool, and more.
+The _unified CLI_ is a still-experimental way of using Nix that involves just one executable called `nix`.
+_All_ Nix functionality is wrapped into this tool, including commands like `nix build` for building [packages] instead of the old `nix-build` tool, `nix develop` for activating Nix [development environments][env] instead of the old `nix-shell` tool, `nix store` for managing the [Nix store][store] instead of the old `nix-store` tool, and more.
Because the unified CLI isn't yet official, it needs to be explicitly enabled in your Nix configuration by adding `nix-command` to your `experimental-features` list.
We won't cover setting up the unified CLI here because the [Determinate Nix Installer][install] both installs it and enables it in your Nix configuration.
### The original CLI \{#original-cli}
-The *original CLI* for Nix is still the official CLI but, as we mention above, not recommended for new Nix users for two reasons:
+The _original CLI_ for Nix is still the official CLI but, as we mention above, not recommended for new Nix users for two reasons:
1. It's incompatible with [Nix flakes][flakes] as it was created before the inception of flakes.
1. It presents significant cognitive overhead in comparison with the [unified CLI](#unified-cli) because it requires you to learn a wide variety of CLI tools, including `nix-build` for building [packages], `nix-shell` for Nix [development environments][env], `nix-store` for managing the [Nix store][store], and several more.
diff --git a/src/pages/concepts/nixos.mdx b/src/content/concepts/nixos.mdx
similarity index 88%
rename from src/pages/concepts/nixos.mdx
rename to src/content/concepts/nixos.mdx
index 7d7d50f1..1a46bbdf 100644
--- a/src/pages/concepts/nixos.mdx
+++ b/src/content/concepts/nixos.mdx
@@ -4,28 +4,19 @@ wip: true
snippet: |
A [Linux](https://www.kernel.org/) distribution based on the [Nix](/concepts/nix) package manager and guided by Nix's core principles
related: ["nix", "nix-language", "nixpkgs"]
-externalSources: [
- {
- title: "The official Nix website",
- href: "https://nixos.org"
- },
- {
- title: "The NixOS wiki",
- href: "https://wiki.nixos.org"
- },
- {
- title: "NixOS",
- href: "https://en.wikipedia.org/wiki/NixOS",
- source: {
- title: "Wikipedia",
- href: "https://wikipedia.org"
- }
- }
-]
+externalSources:
+ [
+ { title: "The official Nix website", href: "https://nixos.org" },
+ { title: "The NixOS wiki", href: "https://wiki.nixos.org" },
+ {
+ title: "NixOS",
+ href: "https://en.wikipedia.org/wiki/NixOS",
+ source: { title: "Wikipedia", href: "https://wikipedia.org" },
+ },
+ ]
---
-
-*NixOS* is a [Linux] distribution based on [Nix].
+_NixOS_ is a [Linux] distribution based on [Nix].
It's unique amongst distributions because it enables you to use the [Nix language][lang] to [declaratively configure][declarative] your operating system in a [`configuration.nix` file](#configuration).
And that configurability runs quite deep, including things like the system's [boot loader][boot], the [filesystem], [window managers][window], [kernel modules][kernel], services like [OpenSSH], and much more.
@@ -43,7 +34,7 @@ Nix enables NixOS to provide a range of unique features.
### Generations
-Unlike other Linux distributions, updates to NixOS system state constitute atomic *generations* with a number.
+Unlike other Linux distributions, updates to NixOS system state constitute atomic _generations_ with a number.
Each time you run `nixos-rebuild switch` to apply your desired [system configuration](#configuration), Nix increments the generation.
One of the core advantages of generations is that you can switch between [atomic versions](#atomicity) of your system state at will.
@@ -61,11 +52,11 @@ Rollbacks are fully [atomic](#atomicity) and include [packages], system configur
### Multi-user support \{#multi-user}
NixOS doesn't follow the [Filesystem Hierarchy Standard][fhs], instead using the [Nix store][store] for everything, including not just [packages] but also [derivations] and other artifacts.
-This enables NixOS to support an indefinite number of user *profiles* in an elegant way.
+This enables NixOS to support an indefinite number of user _profiles_ in an elegant way.
Two different users on the same NixOS host can use different versions of [Git], for example, because instead of sharing a global `git` in a location like `/usr/bin/git`, two different users can use `git` executables from Nix store paths instead:
-* `/nix/store/sglc12hc6pc68w5ppn2k56n6jcpaci16-git-2.38.1/bin/git`
-* `/nix/store/8nwsswymka208dpmsy09aydgffvg4bbi-git-2.38.0/bin/git`
+- `/nix/store/sglc12hc6pc68w5ppn2k56n6jcpaci16-git-2.38.1/bin/git`
+- `/nix/store/8nwsswymka208dpmsy09aydgffvg4bbi-git-2.38.0/bin/git`
Below is a diagram of the first path above:
@@ -83,7 +74,7 @@ With most Linux distributions, you assemble your desired system in a procedural
By contrast, NixOS enables you to define your desired system using the [Nix language][lang]. By default, this is in a `configuration.nix` file stored in `/etc/nixos`.
Here's an example configuration:
-```nix filename=/etc/nixos/configuration.nix
+```nix title="/etc/nixos/configuration.nix"
{ pkgs, ... }: # A pinned version of Nixpkgs passed to the configuration by Nix
{
@@ -125,7 +116,7 @@ Here's an example configuration:
This command applies the configuration above:
-```shell
+```shell title="Rebuild your NixOS system"
nixos-rebuild switch
```
@@ -133,12 +124,13 @@ No complex shell scripts, no sequence of install or build commands, just a singl
### Modules
-A *module* is a piece of Nix code that you can configure to produce configuration.
+A _module_ is a piece of Nix code that you can configure to produce configuration.
In NixOS, a module is a function that takes an attribute set and returns another attribute set.
The basic anatomy of a module can be seen in this code snippet:
-```nix filename=/etc/nixos/configuration.nix
+```nix title="/etc/nixos/configuration.nix"
{ lib, config, pkgs, ... }:
+
{
imports = [];
config = {};
@@ -146,19 +138,18 @@ The basic anatomy of a module can be seen in this code snippet:
}
```
-
+
When you first have a look at NixOS you will undoubtedly see a `configuration.nix` file in `/etc/nixos/`.
Furthermore, if you look at other people's NixOS configurations, you might not see this exact structure.
For one, the input set can be shortened (in the most extreme case to just `{ ... }`).
-See the [Nix syntax](/concepts/nix#basic_syntax) section for details on what this does.
+See the [Nix syntax](/concepts/nix) section for details on what this does.
Additionally, there is some syntactic sugar around NixOS modules, which allow you to omit the `config` key, if your module does not declare any `options`.
As an example, these two modules are equivalent to each other.
-```nix
+```nix title="Equivalent NixOS modules"
# Module 1
-
{ ... }:
{
imports = [ ./my-fish-config.nix ];
@@ -174,6 +165,7 @@ As an example, these two modules are equivalent to each other.
};
}
```
+
### How to use modules
@@ -184,8 +176,9 @@ Instead, you describe the desired outcome of a system, which Nix then produces f
Following is an example of how to setup and configure the [nginx] web server.
-```nix
+```nix title="nginx web server example"
{ ... }:
+
{
services.nginx = {
enable = true;
diff --git a/src/pages/concepts/nixpkgs.mdx b/src/content/concepts/nixpkgs.mdx
similarity index 55%
rename from src/pages/concepts/nixpkgs.mdx
rename to src/content/concepts/nixpkgs.mdx
index 0883d356..30e7da81 100644
--- a/src/pages/concepts/nixpkgs.mdx
+++ b/src/content/concepts/nixpkgs.mdx
@@ -4,35 +4,28 @@ wip: true
snippet: |
A collection of tens of thousands of Nix [packages](/concepts/packages) and build utilities for the [Nix language](/concepts/nix-language)
related: ["channels", "flakes", "nix", "nix-language", "nixos"]
-externalSources: [
- {
- title: "The Nixpkgs repository",
- href: "https://github.com/NixOS/nixpkgs",
- source: {
- title: "GitHub",
- href: "https://github.com"
- }
- },
- {
- title: "The Nixpkgs manual",
- href: "https://nixos.org/manual/nixpkgs/stable/",
- source: {
- title: "The official Nix documentation",
- href: "https://nixos.org"
- }
- },
- {
- title: "Nixpkgs",
- href: "https://wiki.nixos.org/wiki/Nixpkgs",
- source: {
- title: "The NixOS wiki",
- href: "https://wiki.nixos.org"
- }
- }
-]
+externalSources:
+ [
+ {
+ title: "The Nixpkgs repository",
+ href: "https://github.com/NixOS/nixpkgs",
+ source: { title: "GitHub", href: "https://github.com" },
+ },
+ {
+ title: "The Nixpkgs manual",
+ href: "https://nixos.org/manual/nixpkgs/stable/",
+ source:
+ { title: "The official Nix documentation", href: "https://nixos.org" },
+ },
+ {
+ title: "Nixpkgs",
+ href: "https://wiki.nixos.org/wiki/Nixpkgs",
+ source: { title: "The NixOS wiki", href: "https://wiki.nixos.org" },
+ },
+ ]
---
-*Nixpkgs* (pronounced "Nix packages") is a big collection of [Nix] expressions, packages (who'd have thought...), and build utilities for the Nix ecosystem.
+_Nixpkgs_ (pronounced "Nix packages") is a big collection of [Nix] expressions, packages (who'd have thought...), and build utilities for the Nix ecosystem.
It is sometimes also called a "Nix standard library" (or Nix stdlib).
Nixpkgs is a mono repo, containing over 80,000 package definitions and the utilities to maintain this set of packages.
diff --git a/src/pages/concepts/package-management.mdx b/src/content/concepts/package-management.mdx
similarity index 67%
rename from src/pages/concepts/package-management.mdx
rename to src/content/concepts/package-management.mdx
index 079d23e7..de9e5ece 100644
--- a/src/pages/concepts/package-management.mdx
+++ b/src/content/concepts/package-management.mdx
@@ -4,26 +4,24 @@ wip: true
snippet: |
The art of building and distributing software [packages](/concepts/packages)
related: ["packages"]
-externalSources: [
- {
- title: "Package manager",
- href: "https://en.wikipedia.org/wiki/Package_manager",
- source: [
- title: "Wikipedia",
- href: "https://wikipedia.org"
- ]
- }
-]
+externalSources:
+ [
+ {
+ title: "Package manager",
+ href: "https://en.wikipedia.org/wiki/Package_manager",
+ source: { title: "Wikipedia", href: "https://wikipedia.org" },
+ },
+ ]
---
-*Package management* is the art of building and distributing software [packages].
+_Package management_ is the art of building and distributing software [packages].
[Nix] is different from package managers like [apt], [dpkg], and [yum] in several important ways:
-* Nix always builds all [packages] from scratch, including the entire [closure], or dependency tree, of that package.
+- Nix always builds all [packages] from scratch, including the entire [closure], or dependency tree, of that package.
But if a dependency is already present in the [Nix store][store] or in a remote cache, Nix can use that instead of rebuilding it, which means that Nix can provide [incremental builds][incremental].
-* Nix has a [language]—also called *Nix*—that you can use to define your own package builds
-* Nix works on several platforms, including Linux, macOS, and Windows WSL.
+- Nix has a [language]—also called _Nix_—that you can use to define your own package builds
+- Nix works on several platforms, including Linux, macOS, and Windows WSL.
[apt]: https://en.wikipedia.org/wiki/APT_(software)
[closure]: /concepts/closures
diff --git a/src/pages/concepts/packages.mdx b/src/content/concepts/packages.mdx
similarity index 89%
rename from src/pages/concepts/packages.mdx
rename to src/content/concepts/packages.mdx
index 727bd31b..b5ea95d7 100644
--- a/src/pages/concepts/packages.mdx
+++ b/src/content/concepts/packages.mdx
@@ -6,7 +6,7 @@ snippet: |
related: ["derivations", "nix-store"]
---
-Nix *packages* are self-contained bundles that are built using [derivations] and provide some kind of software or dependencies of software on your computer.
+Nix _packages_ are self-contained bundles that are built using [derivations] and provide some kind of software or dependencies of software on your computer.
A package can have dependencies on other packages, which are encoded in its [closure].
Each package lives at a unique path in the [Nix store](/concepts/nix-store) indexed by its name and its input hash.
diff --git a/src/pages/concepts/pinning.mdx b/src/content/concepts/pinning.mdx
similarity index 67%
rename from src/pages/concepts/pinning.mdx
rename to src/content/concepts/pinning.mdx
index f39a0f8b..a9a10c1e 100644
--- a/src/pages/concepts/pinning.mdx
+++ b/src/content/concepts/pinning.mdx
@@ -4,27 +4,25 @@ wip: true
snippet: |
Fixing a [Nix](/concepts/nix) dependency to a specific revision
related: ["derivations", "flakes"]
-externalSources: [
- {
- title: "Toward reproducibility: pinning Nixpkgs",
- href: "https://nix.dev/tutorials/towards-reproducibility-pinning-nixpkgs",
- source: {
- title: "nix.dev",
- href: "https://nix.dev"
- }
- }
-]
+externalSources:
+ [
+ {
+ title: "Toward reproducibility: pinning Nixpkgs",
+ href: "https://nix.dev/tutorials/first-steps/towards-reproducibility-pinning-nixpkgs",
+ source: { title: "nix.dev", href: "https://nix.dev" },
+ },
+ ]
---
-*Pinning* a dependency refers to the act of specifying an exact revision for Nix to use.
+_Pinning_ a dependency refers to the act of specifying an exact revision for Nix to use.
This is particularly interesting in relation to Nix's [reproducibility](/concepts/reproducibility) guarantees.
-When you pin Nix dependencies to a specific revision you are guaranteed to get the same outputs of builds, based on the same inputs, which can not change.
+When you pin Nix dependencies to a specific revision you are guaranteed to get the same outputs of builds, based on the same inputs, which cannot change.
This is particularly useful when sharing environments between different developers, or between a development and production environment.
Pinning dependencies can be done in the `inputs` section of the flakes file:
-```nix
+```nix title="flake.nix"
{
inputs = {
nixpkgs.url = "git+https://github:nixos/nixpkgs?rev=fdc8ef970de2b4634e1b3dca296e1ed918459a9e";
diff --git a/src/pages/concepts/provenance.mdx b/src/content/concepts/provenance.mdx
similarity index 76%
rename from src/pages/concepts/provenance.mdx
rename to src/content/concepts/provenance.mdx
index bad05a89..0f82f06e 100644
--- a/src/pages/concepts/provenance.mdx
+++ b/src/content/concepts/provenance.mdx
@@ -3,19 +3,17 @@ title: Provenance
wip: true
snippet: The origin of a piece of software
related: ["derivations", "packages", "realisation", "reproducibility"]
-externalSources: [
- {
- title: "Provenance",
- href: "https://wikipedia.org/wiki/Provenance",
- source: {
- title: "Wikipedia",
- href: "https://wikipedia.org"
- }
- }
-]
+externalSources:
+ [
+ {
+ title: "Provenance",
+ href: "https://wikipedia.org/wiki/Provenance",
+ source: { title: "Wikipedia", href: "https://wikipedia.org" },
+ },
+ ]
---
-*Provenance* is a term that's basically synonymous for the origins of a thing.
+_Provenance_ is a term that's basically synonymous for the origins of a thing.
In software, provenance usually refers to the build process that created an artifact (a program, a file, a smartphone app, and so on).
Without establishing the provenance of a piece of software—like the code it was built from or the server it was downloaded from—it's hard to know how much you should trust that piece of software.
diff --git a/src/pages/concepts/realisation.mdx b/src/content/concepts/realisation.mdx
similarity index 70%
rename from src/pages/concepts/realisation.mdx
rename to src/content/concepts/realisation.mdx
index 8a535e7c..9674b5ac 100644
--- a/src/pages/concepts/realisation.mdx
+++ b/src/content/concepts/realisation.mdx
@@ -4,25 +4,27 @@ wip: true
snippet: |
The process whereby Nix turns the build instruction in a [derivation](/concepts/derivations) into a build output in the [Nix store](/concepts/nix-store)
related: ["derivations", "nix-store", "packages"]
-externalSources: [
- {
- title: "How to learn Nix, part 29: derivations in detail",
- href: "https://ianthehenry.com/posts/how-to-learn-nix/derivations-in-detail",
- source: {
- title: "Ian Henry's blog",
- href: "https://ianthehenry.com/posts/how-to-learn-nix"
- }
- }
-]
+externalSources:
+ [
+ {
+ title: "How to learn Nix, part 29: derivations in detail",
+ href: "https://ianthehenry.com/posts/how-to-learn-nix/derivations-in-detail",
+ source:
+ {
+ title: "Ian Henry's blog",
+ href: "https://ianthehenry.com/posts/how-to-learn-nix",
+ },
+ },
+ ]
---
-*Realisation* is the process whereby a Nix [derivation] is transformed into a [package].
+_Realisation_ is the process whereby a Nix [derivation] is transformed into a [package].
While a derivation is essentially a plan for a package, realisation is the build process turns that plan into an actual output directory full of content.
## `.drv` files
When you run [`nix build`][nix-build] to build a package, the Nix CLI first looks at the [`derivation`][derivation] function for the function and transforms it into an intermediate [`.drv` file][drv], which is essentially a formal representation of the `derivation` function.
-All `.drv` files are stored in the [Nix store][store] with a hashed path, such as `/nix/store/m2nb4d0pfydr8bq5ww1yqbrkvvf18zbl-perl-5.36.0.drv`, which ensures that *any* change in a `derivation` function results in a new `.drv` file with a new path.
+All `.drv` files are stored in the [Nix store][store] with a hashed path, such as `/nix/store/m2nb4d0pfydr8bq5ww1yqbrkvvf18zbl-perl-5.36.0.drv`, which ensures that _any_ change in a `derivation` function results in a new `.drv` file with a new path.
The CLI then uses the `.drv` file as the blueprint for the actual build process, which always builds the package's entire dependency tree.
## The build process
@@ -32,7 +34,7 @@ Everything required for the build process is drawn from:
1. The build instructions in the derivation. For example, commands like `cat`, `touch`, `mkdir`, and `mv`.
1. Artifacts from the [Nix store][store].
- If you write a derivation with [Git] as a build input, for example, the realisation process builds Git and stores the resulting package in the [Nix store][store] (if it isn't already built and stored there) and uses that package when the `git` command is invoked in the build logic, rather than a "global" Git at a path like `/usr/bin/git`.
+ If you write a derivation with [Git] as a build input, for example, the realisation process builds Git and stores the resulting package in the [Nix store][store] (if it isn't already built and stored there) and uses that package when the `git` command is invoked in the build logic, rather than a "global" Git at a path like `/usr/bin/git`.
[derivation]: /concepts/derivations
[drv]: https://nixos.org/guides/nix-pills/our-first-derivation
diff --git a/src/pages/concepts/reproducibility.mdx b/src/content/concepts/reproducibility.mdx
similarity index 75%
rename from src/pages/concepts/reproducibility.mdx
rename to src/content/concepts/reproducibility.mdx
index d4382e1b..21eff7ef 100644
--- a/src/pages/concepts/reproducibility.mdx
+++ b/src/content/concepts/reproducibility.mdx
@@ -9,36 +9,32 @@ externalSources:
{
title: "When is a build reproducible?",
href: "https://reproducible-builds.org/docs/definition",
- source: {
- title: "The Reproducible Builds project",
- href: "https://reproducible-builds.org"
- }
+ source:
+ {
+ title: "The Reproducible Builds project",
+ href: "https://reproducible-builds.org",
+ },
},
{
title: "Reproducibility",
href: "https://en.wikipedia.org/wiki/Reproducibility",
- source: {
- title: "Wikipedia",
- href: "https://wikipedia.org"
- }
+ source: { title: "Wikipedia", href: "https://wikipedia.org" },
},
{
title: "Reproducible builds",
href: "https://en.wikipedia.org/wiki/Reproducible_builds",
- source: {
- title: "Wikipedia",
- href: "https://wikipedia.org"
- }
- }
+ source: { title: "Wikipedia", href: "https://wikipedia.org" },
+ },
]
---
-*Reproducibility* is a software design concept, where an operation for the same inputs yields the same output.
+_Reproducibility_ is a software design concept, where an operation for the same inputs yields the same output.
This is an important property for Nix, because hashes are based on the inputs of a build,
and thus it must be guaranteed that the same inputs yield in the same build output.
-```nix
+```nix title="Example derivation"
{ stdenv, fetchGit }:
+
stdenv.mkDerivation {
name = "my-package";
src = fetchgit {
@@ -48,12 +44,12 @@ stdenv.mkDerivation {
}
```
-The above code consists of *two* derivations: `fetchgit` and `mkDerivation`.
+The above code consists of _two_ derivations: `fetchgit` and `mkDerivation`.
The reproducibility of `mkDerivation` is guaranteed because the output of `fetchgit` is pinned to a particular hash.
And because `mkDerivation` itself isn't allowed to touch the network, and is [hermetically](/concepts/hermeticity) sealed from the host, no impurities in the build can exist.
The output of `fetchgit` is guaranteed because its output is fixed to a particular hash.
-While it *can* touch the network, it will fail to build if the output from the fetch doesn't match the user-provided output hash.
+While it _can_ touch the network, it will fail to build if the output from the fetch doesn't match the user-provided output hash.
You can see how the reproducibility of Nix builds are layered, like a packaging onion.
diff --git a/src/pages/concepts/sandboxing.mdx b/src/content/concepts/sandboxing.mdx
similarity index 73%
rename from src/pages/concepts/sandboxing.mdx
rename to src/content/concepts/sandboxing.mdx
index e31bde86..af6dcdf6 100644
--- a/src/pages/concepts/sandboxing.mdx
+++ b/src/content/concepts/sandboxing.mdx
@@ -6,11 +6,11 @@ snippet: |
related: ["derivations", "nix-store", "packages", "realisation"]
---
-Whenever Nix builds anything, it *sandboxes* that process from everything else on the host system.
+Whenever Nix builds anything, it _sandboxes_ that process from everything else on the host system.
Nix builds are sandboxed for a variety of reasons:
1. The ensure [reproducibility].
- Sandboxing ensures that no system state on the host machine affects the build outcomes.
+ Sandboxing ensures that no system state on the host machine affects the build outcomes.
1. To maintain strict [provenance].
[reproducibility]: /concepts/reproducibility
diff --git a/src/pages/concepts/system-specificity.mdx b/src/content/concepts/system-specificity.mdx
similarity index 93%
rename from src/pages/concepts/system-specificity.mdx
rename to src/content/concepts/system-specificity.mdx
index db7f192b..4627e57e 100644
--- a/src/pages/concepts/system-specificity.mdx
+++ b/src/content/concepts/system-specificity.mdx
@@ -6,7 +6,7 @@ snippet: |
related: ["derivations", "packages"]
---
-In Nix, the term *system specificity* expresses the fact that all Nix [derivations] have a `system` attribute that specifies which system the derivation is built on.
+In Nix, the term _system specificity_ expresses the fact that all Nix [derivations] have a `system` attribute that specifies which system the derivation is built on.
In order to realize a Nix derivation into a [package], each derivation in the package's closure needs to be supported on the target system.
So if you want to build the package `foo` on an `x86_64-linux` system, any dependency of the `foo` derivation needs to be supported on `x86_64-linux`.
diff --git a/src/content/config.ts b/src/content/config.ts
new file mode 100644
index 00000000..99b1475c
--- /dev/null
+++ b/src/content/config.ts
@@ -0,0 +1,53 @@
+import { defineCollection, z } from "astro:content";
+
+const briefs = defineCollection({
+ type: "content",
+ schema: z.object({
+ id: z.string(),
+ }),
+});
+
+const concepts = defineCollection({
+ type: "content",
+ schema: z.object({
+ title: z.string(),
+ snippet: z.string(),
+ wip: z.boolean().default(false),
+ // TODO: make this tighter
+ related: z.array(z.string()),
+ externalSources: z
+ .array(
+ z.object({
+ title: z.string(),
+ href: z.string().url(),
+ source: z
+ .object({
+ title: z.string(),
+ href: z.string().url(),
+ })
+ .optional(),
+ }),
+ )
+ .optional(),
+ }),
+});
+
+// Top-level pages like /about
+const plain = defineCollection({
+ type: "content",
+ schema: z.object({
+ title: z.string(),
+ description: z.string(),
+ }),
+});
+
+const start = defineCollection({
+ type: "content",
+ schema: z.object({
+ title: z.string(),
+ order: z.number(),
+ summary: z.array(z.string()).optional(),
+ }),
+});
+
+export const collections = { briefs, concepts, plain, start };
diff --git a/src/pages/about.mdx b/src/content/plain/about.mdx
similarity index 99%
rename from src/pages/about.mdx
rename to src/content/plain/about.mdx
index 815b71da..67c6a054 100644
--- a/src/pages/about.mdx
+++ b/src/content/plain/about.mdx
@@ -1,7 +1,6 @@
---
title: About Zero to Nix
description: What it is, why we made it, and how it fits into the [Nix](/concepts/nix) ecosystem
-layout: plain
---
[**Zero to Nix**](/) is a highly opinionated learning resource for [Nix] created by Determinate Systems. We believe Zero to Nix fills a major gap for two reasons:
diff --git a/src/pages/start/1.install.mdx b/src/content/start/1.install.mdx
similarity index 71%
rename from src/pages/start/1.install.mdx
rename to src/content/start/1.install.mdx
index 5a0dc5a0..ba10289f 100644
--- a/src/pages/start/1.install.mdx
+++ b/src/content/start/1.install.mdx
@@ -1,13 +1,14 @@
---
title: Get Nix running on your system
-path: /start/install
-summary: [
- "Get [Nix](/concepts/nix) running on your Linux or macOS system using [nix-installer](/concepts/nix-installer)",
- "Verify that your installed Nix is working as expected"
-]
+order: 1
+summary:
+ [
+ "Get [Nix](/concepts/nix) running on your Linux or macOS system using [nix-installer](/concepts/nix-installer)",
+ "Verify that your installed Nix is working as expected",
+ ]
---
-
+
We wrote this [Zero to Nix][z2n] quick start with one specific audience in mind: people who have heard about [Nix] but don't yet know much about it and aren't quite sure where to start with the learning process.
It's intended less as a how-to guide for using Nix in your everyday workflows and more to provide a glimpse into Nix's feature set and to provide some of those "a-ha!" moments that make you feel empowered to go further.
@@ -21,18 +22,18 @@ In this [quick start][start], we'll get Nix installed on your system and provide
We recommend installing Nix using the [Determinate Nix installer][nix-installer], a tool from [Determinate Systems][detsys] that tailors the installation process to your system.
The installer supports these platforms:
-Platform | Multi user? | `root` only
-:--------|:------------|:-----------
-Linux on 64-bit ARM and 64-bit AMD/Intel | ✅ (via [systemd]) | ✅
-macOS on 64-bit ARM and 64-bit AMD/Intel | ✅ |
-[Valve Steam Deck][steamdeck] (SteamOS) | ✅ |
-[Windows Subsystem for Linux][wsl] (WSL) on 64-bit ARM and 64-bit AMD/Intel | ✅ (via [systemd]) | ✅
-[Podman] Linux containers | ✅ (via [systemd]) | ✅
-[Docker] containers | | ✅
+| Platform | Multi user? | `root` only? |
+| :-------------------------------------------------------------------------- | :----------------- | :----------- |
+| Linux on 64-bit ARM and 64-bit AMD/Intel | ✅ (via [systemd]) | ✅ |
+| macOS on 64-bit ARM and 64-bit AMD/Intel | ✅ | |
+| [Valve Steam Deck][steamdeck] (SteamOS) | ✅ | |
+| [Windows Subsystem for Linux][wsl] (WSL) on 64-bit ARM and 64-bit AMD/Intel | ✅ (via [systemd]) | ✅ |
+| [Podman] Linux containers | ✅ (via [systemd]) | ✅ |
+| [Docker] containers | | ✅ |
-To run the installer:
+## Run the installer \{#run}
-```shell
+```shell title="One command to install Nix"
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
```
@@ -41,13 +42,13 @@ If you have concerns about the "curl to Bash" approach you have two options:
1. You can download a binary for the most recent version of the Determinate Nix Installer directly from the [releases] page and run it.
1. You can examine the installation script [here][script] then download and run it:
- ```shell
- curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix > nix-installer.sh
- chmod +x nix-installer.sh
- ./nix-installer.sh install
- ```
+ ```shell title="Inspect the script, then install"
+ curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix > nix-installer.sh
+ chmod +x nix-installer.sh
+ ./nix-installer.sh install
+ ```
-
+
We believe that the Determinate Nix Installer provides a smoother experience for people who are new to Nix than the [official Nix installation script][official].
Unlike many tools, Nix needs to make several changes to your system in order to work properly, such as creating a new `/nix` directory, configuring your shell profile, and creating several new system users and groups.
@@ -55,6 +56,7 @@ The Determinate Nix Installer improves on the official Nix installation script b
It also installs Nix with [Nix flakes][flakes] enabled while the official installer requires you to enable flakes manually.
See the [Uninstalling Nix][uninstall] guide if you need to uninstall Nix or the [Determinate Nix Installer][nix-installer] concept doc if you'd like more background.
+
Validate the displayed plan and approve it to begin the installation process.
@@ -63,7 +65,7 @@ Once the installer has finished, you should see `Nix was installed successfully!
Open a new terminal session and the `nix` executable should be in your `$PATH`.
To verify that:
-```bash
+```shell title="Display the Nix version"
nix --version
```
@@ -72,8 +74,9 @@ This should print the version information for Nix.
:rocket: **Success**!
You now have Nix installed and ready to go on your system.
-
-If you're interested in contributing to Zero to Nix, see the [manual][contributing] in the project [repo] for some suggestions.
+
+ If you're interested in contributing to Zero to Nix, see the
+ [manual][contributing] in the project [repo] for some suggestions.
[apfs]: https://es.wikipedia.org/wiki/Apple_File_System
diff --git a/src/pages/start/2.nix-run.mdx b/src/content/start/2.nix-run.mdx
similarity index 74%
rename from src/pages/start/2.nix-run.mdx
rename to src/content/start/2.nix-run.mdx
index 60b961e5..03c9aeca 100644
--- a/src/pages/start/2.nix-run.mdx
+++ b/src/content/start/2.nix-run.mdx
@@ -1,6 +1,6 @@
---
title: Run a program with Nix
-path: /start/nix-run
+order: 2
summary:
[
"Use the `nix run` command to run a program from [Nixpkgs](/concepts/nixpkgs)",
@@ -13,38 +13,42 @@ In the last section, we installed Nix using the [Determinate Nix Installer][nix-
Now we can dive in and use Nix to run an actual program.
Let's try running the delightful [ponysay]:
-```shell
+```shell title="Pass a string to Ponysay"
echo "Hello Nix" | nix run "https://flakehub.com/f/NixOS/nixpkgs/*#ponysay"
```
:rocket: **Success**!
You should see a charming equine greeting in your console.
-
-The first time you run a program using `nix run` it's likely to be a slow operation.
-That's because Nix needs to build the program's [package][packages] from scratch—or download it from a known [cache]—and store it in the [Nix store][store].
-This is in contrast to most [package managers][pkg], which install things more quickly because they download pre-built archives like tarballs.
-Future `nix run` invocations should be instantaneous, as Nix doesn't need to build the package again.
+
+ The first time you run a program using `nix run` it's likely to be a slow
+ operation. That's because Nix needs to build the program's [package][packages]
+ from scratch—or download it from a known [cache]—and store it in
+ the [Nix store][store]. This is in contrast to most [package managers][pkg],
+ which install things more quickly because they download pre-built archives
+ like tarballs. Future `nix run` invocations should be instantaneous, as Nix
+ doesn't need to build the package again.
## Explanation
What happened here? The [Nix] CLI did a few things:
-* It used a [flake reference][ref] to [Nixpkgs] to pull in some Nix code and targeted the `ponysay` [flake output][output] (more on this later).
-* It built the [`ponysay` package][ponysay] and stored the result in the [Nix store][store].
-* It ran the executable at `bin/ponysay` from the `ponysay` package.
+- It used the `nixpkgs` [flake reference][ref] to pull in some Nix code and targeted the `ponysay` [flake output][output] (more on this later).
+- It built the [`ponysay` package][ponysay] and stored the result in the [Nix store][store].
+- It ran the executable at `bin/ponysay` from the `ponysay` package.
In Nix, every program is part of a [package][packages].
Packages are built using the [Nix language][derivations].
The `ponysay` package has a single program (also called `ponysay`) but packages can contain multiple programs as well as man pages, configuration files, and more.
The [`ffmpeg`][ffmpeg-pkg] package, for example, provides both [ffmpeg] and [ffprobe].
-
+
You may have noticed that [`nix run`][nix-run] doesn't require anything like a `nix install` command.
This makes it handy for use cases like shell scripting or experimenting with in-progress tools.
For more on `nix run`, see [Using Nix to run software with no installation steps][nix-run-post] on the [Determinate Systems blog][blog].
+
**Congrats**!
diff --git a/src/pages/start/3.nix-develop.mdx b/src/content/start/3.nix-develop.mdx
similarity index 68%
rename from src/pages/start/3.nix-develop.mdx
rename to src/content/start/3.nix-develop.mdx
index 783e9276..d7c4c5a2 100644
--- a/src/pages/start/3.nix-develop.mdx
+++ b/src/content/start/3.nix-develop.mdx
@@ -1,6 +1,6 @@
---
title: Explore Nix development environments
-path: /start/nix-develop
+order: 3
summary: [
"Use the `nix develop` command to activate a Nix development environment",
"Run a command inside a development environment without actually entering that environment",
@@ -16,20 +16,23 @@ We'll cover that a bit later, but for now let's get a feel for what a Nix develo
The [`nix develop`][nix-develop] command activates a Nix environment:
-```shell
+```shell title="Enter a Nix development environment defined in an external flake"
nix develop "https://flakehub.com/f/DeterminateSystems/zero-to-nix/*#example"
```
-
-The first time you activate a Nix development environment using `nix develop` it's likely to be a slow operation.
-That's because Nix needs to build every [package][packages] included in the environment from scratch.
-This is in contrast to most [package managers][pkg], which install things more quickly because they download pre-built archives like tarballs.
-Future `nix develop` invocations should be much faster, as Nix doesn't need to build the packages again.
+
+ The first time you activate a Nix development environment using `nix develop`
+ it's likely to be a slow operation. That's because Nix needs to build every
+ [package][packages] included in the environment from scratch. This is in
+ contrast to most [package managers][pkg], which install things more quickly
+ because they download pre-built archives like tarballs. Future `nix develop`
+ invocations should be much faster, as Nix doesn't need to build the packages
+ again.
You should be greeted by a new shell prompt, something like this:
-```shell
+```shell title="Shell prompt in the Nix development environment"
(nix:zero-to-nix-env) bash-5.2$
```
@@ -37,7 +40,7 @@ You should be greeted by a new shell prompt, something like this:
You're now in a [Bash] environment that includes [curl] and [Git].
You may already have both in your environment, but run these commands to see that something new is happening:
-```shell
+```shell title="Ensure that curl and Git are installed"
type curl
type git
```
@@ -48,31 +51,36 @@ For curl, for example, you should see a strange path like this (the hash part sh
What happened here? The [Nix] CLI did a few things:
-* It used the `https://flakehub.com/f/DeterminateSystems/zero-to-nix/*#example` [flake reference][flakes] to pull in some Nix code and built a specific [flake output][output] (more on this later).
-* It built the [packages] specified in the environment configuration (again, more on this later).
-* It set up an environment with a [`PATH`][path] that enables the `git` and `curl` packages to be discovered in the [Nix store][store].
+- It used the `https://flakehub.com/f/DeterminateSystems/zero-to-nix/*#example` [flake reference][flakes] to pull in some Nix code and built a specific [flake output][output] (more on this later).
+- It built the [packages] specified in the environment configuration (again, more on this later).
+- It set up an environment with a [`PATH`][path] that enables the `git` and `curl` packages to be discovered in the [Nix store][store].
Two other things that you can provide in Nix development environments:
-1. Although this example doesn't include one, you can define *shell hooks*, which are arbitrary shell code that runs whenever the environment starts up.
- Some example use cases for shell hooks:
- * `echo` information about the environment to the console whenever the environment is activated
- * Run things like checks and linters
- * Ensure that other desired hooks, like [Git hooks][hooks], are properly set up.
- Run this to see an example shell hook:
+1. Although this example doesn't include one, you can define _shell hooks_, which are arbitrary shell code that runs whenever the environment starts up.
+ Some example use cases for shell hooks:
+ - `echo` information about the environment to the console whenever the environment is activated
+ - Run things like checks and linters
+ - Ensure that other desired hooks, like [Git hooks][hooks], are properly set up.
+ Run this to see an example shell hook:
+
+ ```shell title="Run a shell hook"
+ nix develop "github:DeterminateSystems/zero-to-nix#hook"
+ ```
+
+1. Nix development environments support environment variables as well.
+ Run `echo $FUNNY_JOKE` to access a (hilarious) value that's available only in the Nix environment.
+ Some example use cases for environment variables:
+ - Set logging levels using `LOG_LEVEL` or whatever is appropriate for the tools you're using.
+ - Set the environment using variables like `NODE_ENV` (for [Node.js]) to `development`, `dev`, and so on.
```shell
nix develop "https://flakehub.com/f/DeterminateSystems/zero-to-nix/*#hook"
```
-1. Nix development environments support environment variables as well.
- Run `echo $FUNNY_JOKE` to access a (hilarious) value that's available only in the Nix environment (then run `exit` to leave the environment).
- Some example use cases for environment variables:
- * Set logging levels using `LOG_LEVEL` or whatever is appropriate for the tools you're using.
- * Set the environment using variables like `NODE_ENV` (for [Node.js]) to `development`, `dev`, and so on.
Let's leave the Nix development environment to prepare for the next section:
-```shell
+```shell title="Leave the environment"
exit
```
@@ -83,124 +91,130 @@ And if you run `echo $FUNNY_JOKE` again you should get an empty string (unless y
## Run commands inside the development environment
While it's fun to explore the environment, you don't always want to be inside the environment to use it.
-The `nix develop` command provides a `--command` (or `-c`) flag that you can use to run commands that *use* the environment but *from* your current environment.
+The `nix develop` command provides a `--command` (or `-c`) flag that you can use to run commands that _use_ the environment but _from_ your current environment.
Here are some examples for the environment we used earlier:
-```shell
+```shell title="Layer multiple environments"
nix develop "https://flakehub.com/f/DeterminateSystems/zero-to-nix/*#example" --command git help
nix develop "https://flakehub.com/f/DeterminateSystems/zero-to-nix/*#example" --command curl https://example.com
```
In both cases, you're running a package in the [Nix store][store] and nothing from your global environment.
-As you can see, Nix development environments are [*hermetic*][hermeticity] in that they're isolated from the surrounding environment (such as your environment variables and paths like `/bin` and `/usr/bin`).
+As you can see, Nix development environments are [_hermetic_][hermeticity] in that they're isolated from the surrounding environment (such as your environment variables and paths like `/bin` and `/usr/bin`).
## Language-specific environments
As we did in the [last section][last], let's get a bit more specific and explore how Nix can benefit more specific programming environments.
Select one of these programming languages:
-
+
-Now explore the Nix development environment for :
+Now explore the Nix development environment for :
-
+
-
+
First, let's see the Nix store path for [CMake]:
-```shell
+```shell title="Get path information for CMake"
type cmake
```
Check the current CMake version:
-```shell
+```shell title="Check CMake's version"
cmake --version
```
+
-
+
First, let's see the Nix store path for the [Glasgow Haskell Compiler][ghc] (GHC):
-```shell
+```shell title="See the store path for GHC"
type ghc
```
Check the current GHC version:
-```shell
+```shell title="Check the GHC's version"
ghc --version
```
+
-
+
First, let's see the Nix store path for [Node.js]:
-```shell
+```shell title="See the store path for Node.js"
type node
```
Now use Node to run a program:
-```shell
+```shell title="Check the Node.js version"
node --eval "console.log('1 + 1 = ' + (1 + 1))"
```
+
-
+
First, let's see the Nix store path for Python:
-```shell
+```shell title="See the store path for Python"
type python
```
Now use Python to run a program:
-```shell
+```shell title="Use Python to run a simple program"
python -c "print(1 + 1)"
```
+
-
+
First, let's see the Nix store path for the [Go] CLI:
-```shell
+```shell title="See the store path for Go"
type go
```
Now check the Go version:
-```shell
+```shell title="Check the Go version"
go version
```
You should get 1.22.5.
-
+
First, let's see the Nix store path for [cargo]:
-```shell
+```shell title="See the store path for Cargo"
type cargo
```
Now create a [Rust] project in the current directory and run the example:
-```shell
+```shell title="Initialize a Rust project and run it"
cargo init ./zero-to-nix-rs
cd ./zero-to-nix-rs
cargo run
```
You should see `Hello, world!`.
+
-
+
First, let's see the Nix store path for [sbt]:
-```shell
+```shell title="See the store path for sbt"
type sbt
```
Check the sbt version inside the environment:
-```shell
+```shell title="Check the sbt version"
sbt --version
```
+
Like usual, run `exit` to leave the Nix environment and return to your usual environment.
@@ -211,7 +225,7 @@ In the [previous section](#language-specific-environments), we explored Nix envi
But Nix environments are infinitely flexible, enabling you to combine whichever packages you like.
Let's explore an example of this:
-```shell
+```shell title="Activate a multi-language development environment"
nix develop "https://flakehub.com/f/DeterminateSystems/zero-to-nix/*#multi"
```
@@ -225,12 +239,21 @@ This Nix environment has several tools available:
As in the previous examples, you can run commands like `type python` and `type kubectl` to see that these tools are all discoverable in the [Nix store][store] and not somewhere like `/usr/bin`.
This list could easily include 100 packages.
It's up to you.
-We won't cover *how* to create these environments just yet, but we hope that you come away from this guide with a basic sense of what Nix development environments provide.
-
-
-[direnv] is a popular tool that automatically loads specific environment variables whenever you `cd` into a directory (and then unloads those variables when you `cd` out of the directory).
-The combination of direnv and Nix can be quite powerful, enabling you to automatically load Nix development environments whenever you navigate to a directory.
-For more info, see [Effortless dev environments with Nix and direnv][nix-direnv] on the [Determinate Systems blog][blog].
+We won't cover _how_ to create these environments just yet, but we hope that you come away from this guide with a basic sense of what Nix development environments provide.
+
+
+ [direnv] is a popular tool that automatically loads specific environment
+ variables whenever you `cd` into a directory (and then unloads those variables
+ when you `cd` out of the directory). The combination of direnv and Nix can be
+ quite powerful, enabling you to automatically load Nix development
+ environments whenever you navigate to a directory. For more info, see
+ [Effortless dev environments with Nix and direnv][nix-direnv] on the
+ [Determinate Systems blog][blog].
## From a local flake \{#flake}
@@ -240,125 +263,130 @@ While using an environment in this way is helpful, it's more common to use a dev
First, tell us which language you prefer:
-
+
-To get started in your project, create an empty directory and initialize a [flake template][templates]:
+To get started in your project, create an empty directory and initialize a [flake template][templates]:
-
+
Once the template has been initialized, run `ls .` to see the contents of the directory, which should include two important files:
- The `flake.nix` file defines the [flake][flakes] for your project.
- The `flake.lock` [pins][pinning] all of the [flake inputs][inputs]—essentially the Nix dependencies—in your `flake.nix` file to specific [Git revisions][rev].
-One of the [flake outputs][output] of this Nix [flake][flakes] is a [development environment][dev] for .
+One of the [flake outputs][output] of this Nix [flake][flakes] is a [development environment][dev] for .
To enter that development environment:
-```shell
+```shell title="Enter a development environment in the current flake"
nix develop
```
Now that we've entered the development environment, we can do some exploring, starting with [Nix store paths][paths].
-
+
Ordinarily when you run `type gcc` on a Unix system, you get a path like `/usr/bin/gcc`.
Try running it in the Nix development environment:
-```shell
+```shell title="Get information about the gcc executable"
type gcc
```
You should see a (rather strange) path like this:
-```shell
+```shell title="Path information for gcc"
gcc is /nix/store/nbrvvx1gyq3as3ghmjz62wlgd8f3zfpf-gcc-wrapper-11.3.0/bin/gcc
```
+
-
+
Ordinarily when you run `type ghc` on a Unix system, you get a path like `/usr/bin/ghc`.
Try running it in the Nix development environment:
-```shell
+```shell title="Get path information for ghc"
type ghc
```
You should see a (rather strange) path like this:
-```shell
+```shell title="Path information for ghc"
ghc is /nix/store/f3qnvw5gxgxxpr275kf97pfcy2n1gv79-ghc-9.2.4/bin/ghc
```
+
-
+
Ordinarily when you run `type node` on a Unix system, you get a path like `/usr/bin/node`.
Try running it in the Nix development environment:
-```shell
+```shell title="Get path information for Node.js"
type node
```
You should see a (rather strange) path like this:
-```shell
+```shell title="Path information for Node.js"
node is /nix/store/i88kh2fd03f5fsd3a948s19gliggd2wd-nodejs-18.12.1/bin/node
```
+
-
+
Ordinarily when you run `type python` on a Unix system, you get a path like `/usr/bin/python`.
Try running it in the Nix development environment:
-```shell
+```shell title="Get path information for Python"
type python
```
You should see a (rather strange) path like this:
-```shell
+```shell title="Path information for Python"
python is /nix/store/cqbfx55481irqgbl3bw8jwf69vjpbp8r-python3-3.11.9/bin/python
```
-
+
Ordinarily when you run `type go` on a Unix system, you get a path like `/usr/bin/go`.
Try running it in the Nix development environment:
-```shell
+```shell title="Get path information for Go"
type go
```
You should see a (rather strange) path like this:
-```shell
+```shell title="Path information for Go"
go is /nix/store/5bcx8rv6sy33xsf5dzkp9q8lfdqrsiwa-go-1.19.4/bin/go
```
-
+
Ordinarily when you run `type cargo` on a Unix system, you get a path like `/usr/bin/cargo`.
Try running it in the Nix development environment:
-```shell
+```shell title="Get path information for cargo"
type cargo
```
You should see a (rather strange) path like this:
-```shell
+```shell title="Path information for cargo"
cargo is /nix/store/zc1nr87147gvmg5nqci8q5cfnzg82vwp-rust-default-1.64.0/bin/cargo
```
+
-
+
Ordinarily when you run `type sbt` on a Unix system, you get a path like `/usr/bin/sbt`.
Try running it in the Nix development environment:
-```shell
+```shell title="Get path information for sbt"
type sbt
```
You should see a (rather strange) path like this:
-```shell
+```shell title="Path information for sbt"
sbt is /nix/store/p0hca7x8g45p5hnh0xjzy5s2bcpy1i9l-sbt-1.7.3/bin/sbt
```
+
Probably not what you expected! What happened here? A few things:
diff --git a/src/pages/start/4.nix-build.mdx b/src/content/start/4.nix-build.mdx
similarity index 80%
rename from src/pages/start/4.nix-build.mdx
rename to src/content/start/4.nix-build.mdx
index 9a0fa8d1..67a0d044 100644
--- a/src/pages/start/4.nix-build.mdx
+++ b/src/content/start/4.nix-build.mdx
@@ -1,12 +1,13 @@
---
title: Build a package using Nix
-path: /start/nix-build
-summary: [
- "Build a Nix [package](/concepts/packages) defined in [Nixpkgs](/concepts/nixpkgs)",
- "Run the package from the local directory",
- "Initialize a [flake template](/concepts/flakes#templates) in your preferred programming language",
- "Build a [Nix package](/concepts/packages) from the `flake.nix` in the template"
-]
+order: 4
+summary:
+ [
+ "Build a Nix [package](/concepts/packages) defined in [Nixpkgs](/concepts/nixpkgs)",
+ "Run the package from the local directory",
+ "Initialize a [flake template](/concepts/flakes#templates) in your preferred programming language",
+ "Build a [Nix package](/concepts/packages) from the `flake.nix` in the template",
+ ]
---
While [Nix] can do many things, [package management][pkg] is the thing that it's perhaps best known for. In this tutorial, we'll use our [installed Nix CLI][install] to build and run some Nix [packages] included in [Nixpkgs]. Later in the guide we'll build and run a Nix package defined in a local [flake].
@@ -15,7 +16,7 @@ While [Nix] can do many things, [package management][pkg] is the thing that it's
Let's start by building [bat], a syntax-highlighted version of [cat] written in [Rust] that has a Nix package defined in [Nixpkgs], in an empty directory (make sure to run this in a directory where you have write access):
-```shell
+```shell title="Build the bat package locally"
mkdir build-nix-package && cd build-nix-package
nix build "https://flakehub.com/f/NixOS/nixpkgs/*#bat"
```
@@ -24,7 +25,7 @@ Here, `nixpkgs` is a [flake reference][ref] to the [NixOS/nixpkgs][nixpkgs-repo]
When the build is done, run `ls .` and you should see something called `result` in the current directory. `result` is actually a [symlink] to the built package in the [Nix store][store], which you can verify:
-```shell
+```shell title="Display the Nix store path for the build result"
readlink result
```
@@ -34,15 +35,15 @@ You should see a path like this (it's likely to be a bit different on your machi
What's happened here is that the Nix CLI has:
-* Downloaded the Nix code in [Nixpkgs]
-* Found a package definition with the name `bat` (code [here][nixpkgs-bat])
-* Used the build instructions for `bat` to build the [package][packages]
-* Stored the result in the [Nix store][store] using Nix's hash-based path system
-{/* TODO: add substitution here and link to future caching doc */}
+- Downloaded the Nix code in [Nixpkgs]
+- Found a package definition with the name `bat` (code [here][nixpkgs-bat])
+- Used the build instructions for `bat` to build the [package][packages]
+- Stored the result in the [Nix store][store] using Nix's hash-based path system
+ {/* TODO: add substitution here and link to future caching doc */}
You can now run bat:
-```shell
+```shell title="Run bat from the local build result"
./result/bin/bat --help
```
@@ -53,62 +54,65 @@ You've built and run a package using Nix.
One of the great things about Nix is that package builds are extremely flexible, which enables you to create packages for things written in just about any programming language. In this section, we'll explore that by building and running packages for tools written in a variety of languages. Select one below to see some examples:
-
+
-
+
Let's build and run [CMake]:
-```shell
+```shell title="Build and then run CMake"
nix build "nixpkgs#cmake"
./result/bin/cmake --help
```
+
-
+
Let's build and run [Pandoc]:
-```shell
+```shell title="Build and then run Pandoc"
nix build "nixpkgs#pandoc"
./result/bin/pandoc --version
```
-
+
Let's build and run [npm]:
-```shell
+```shell title="Build and then run npm"
nix build "nixpkgs#nodePackages.npm"
./result/bin/npm --help
```
If you run `ls result/bin` you'll notice that the package also includes [npx].
-
+
Let's build and run [pip]:
-```shell
+```shell title="Build and then run pip"
nix build "nixpkgs#python3Packages.pip"
./result/bin/pip --help
```
+
-
+
Let's build and run [kubectl]:
-```shell
+```shell title="Build and then run kubectl"
nix build "nixpkgs#kubectl"
./result/bin/kubectl --help
```
+
-
+
Let's build and run [ripgrep]:
-```shell
+```shell title="Build and then run ripgrep"
nix build "nixpkgs#ripgrep"
./result/bin/rg --help
```
-
+
Let's build and run [scalafmt]:
-```shell
+```shell title="Build and then run scalafmt"
nix build "nixpkgs#scalafmt"
./result/bin/scalafmt --version
```
@@ -118,14 +122,14 @@ nix build "nixpkgs#scalafmt"
While [Nixpkgs] is by far the largest Nix package repository in the known universe, any [Nix flake][flake] can include package [outputs]. Let's build a package from a different repo, this time the package for [Home Manager][hm], a popular Nix tool for configuring home environments:
-```shell
+```shell title="Build Home Manager"
nix build "https://flakehub.com/f/nix-community/home-manager/*"
```
Here, `https://flakehub.com/f/nix-community/home-manager/*` is a flake reference to the [nix-community/home-manager][hm] repo on FlakeHub.
To run Home Manager:
-```shell
+```shell title="Run Home Manager from the build result"
./result/bin/home-manager --help
```
@@ -138,25 +142,25 @@ In this guide, we'll dig a bit deeper and build a Nix package defined in a local
As above, select a preferred language:
-
+
-To get started in your project, create an empty directory and initialize a [flake template][templates]:
+To get started in your project, create an empty directory and initialize a [flake template][templates]:
-
+
Whichever language you've selected, you can build the [Nix package][packages] defined in the local flake by running:
-```shell
+```shell title="Build a Nix package in the local flake"
nix build
```
This command determines that the local flake has a [package output][outputs] that defines how the package is built.
In this particular flake there's a `default` package, which enables us to run `nix build` without specifying an output, but if the package were output as `packages.mypkg`, for example, we'd need to run `nix build .#mypkg` to build it.
-
+
Here's the package definition that builds our C++ package:
-```nix filename=flake.nix
+```nix title="flake.nix"
{
packages = forAllSystems ({ pkgs }: {
default = pkgs.stdenv.mkDerivation {
@@ -181,20 +185,21 @@ What you see here is a [derivation] that defines how to build the package, more
The package that results when you run `nix build` is a CLI tool that outputs a message.
To run that tool:
-```shell
+```shell title="Run the compiled binary"
./result/bin/zero-to-nix-cpp
```
You should see this output:
-```shell
+```shell title="Expected output"
Hello from Nix + C++!
```
+
-
+
Here's the package definition that builds our Haskell package:
-```nix filename=flake.nix
+```nix title="flake.nix"
{
packages.default = pkgs.haskellPackages.mkDerivation {
pname = "zero-to-nix-haskell";
@@ -214,20 +219,21 @@ What you see here is a [derivation] that defines how to build the package, more
The package that results when you run `nix build` is a CLI tool that outputs a message.
To run that tool:
-```shell
+```shell title="Run the compiled binary"
./result/bin/zero-to-nix-haskell
```
You should see this output:
-```shell
+```shell title="Expected output"
Hello from inside a Haskell program built with Nix!
```
+
-
+
Here's the package definition that builds our JavaScript package:
-```nix filename=flake.nix
+```nix title="flake.nix"
{
packages.default = pkgs.buildNpmPackage {
name = "zero-to-nix-javascript";
@@ -256,16 +262,19 @@ What you see here is a [derivation] that defines how to build the package, more
The package that results when you run `nix build` is a website built using the [Vite] framework.
To view that website, open the HTML file at `result/index.html`.
+
-
+
Here's the package definition that enables us to build our Python package:
-```nix filename=flake.nix
- packages.default = python.pkgs.buildPythonApplication {
- name = "zero-to-nix-python";
- src = self;
- buildInputs = with python.pkgs; [ pip ];
-};
+```nix title="flake.nix"
+{
+ packages.default = python.pkgs.buildPythonApplication {
+ name = "zero-to-nix-python";
+ src = self;
+ buildInputs = with python.pkgs; [ pip ];
+ };
+}
```
For the full flake, see [`flake.nix`][flake-py] on GitHub or run `cat flake.nix`.
@@ -274,7 +283,7 @@ What you see here is a [derivation] that defines how to build the package, more
The resulting package is an executable that prints to the terminal.
To run the package:
-```shell
+```shell title="Run the built executable"
./result/bin/zero-to-nix-python
```
@@ -283,16 +292,19 @@ You should see this terminal output:
```text
Hello from inside a Python program built with Nix!
```
+
-
+
Here's the package definition that enables us to build this Go package:
-```nix filename=flake.nix
-packages.default = pkgs.buildGoModule {
- name = "zero-to-nix-go";
- src = self;
- vendorSha256 = "sha256-fwJTg/HqDAI12mF1u/BlnG52yaAlaIMzsILDDZuETrI=";
-};
+```nix title="flake.nix"
+{
+ packages.default = pkgs.buildGoModule {
+ name = "zero-to-nix-go";
+ src = ./.;
+ vendorSha256 = "sha256-fwJTg/HqDAI12mF1u/BlnG52yaAlaIMzsILDDZuETrI=";
+ };
+}
```
For the full flake, see [`flake.nix`][flake-go] on GitHub or run `cat flake.nix`.
@@ -301,23 +313,25 @@ What you see here is a [derivation] that defines how to build the package, more
The package that results when you run `nix build` is a web server built using the [Gin] framework.
To run the package:
-```shell
+```shell title="Run the compiled binary"
./result/bin/zero-to-nix-go
```
In another window, run `curl http://localhost:8080` to receive a message from the server.
+
-
+
Here's the package definition that enables us to build this Rust package:
-```nix filename=flake.nix
- packages.default = pkgs.rustPlatform.buildRustPackage {
- name = "zero-to-nix-rust";
- src = self;
- cargoLock = {
- lockFile = ./Cargo.lock;
- };
-};
+```nix title="flake.nix"
+{
+ packages.default = pkgs.rustPlatform.buildRustPackage {
+ name = "zero-to-nix-rust";
+ src = ./.;
+ cargoLock = {
+ lockFile = ./Cargo.lock;
+ };
+}
```
For the full flake, see [`flake.nix`][flake-rs] on GitHub or run `cat flake.nix`.
@@ -325,7 +339,7 @@ What you see here is a [derivation] that defines how to build the package, more
To run the resulting package, which is an executable that prints to the terminal:
-```shell
+```shell title="Run the compiled binary"
./result/bin/zero-to-nix-rust
```
@@ -334,15 +348,16 @@ You should see this terminal output:
```text
Hello from Nix + Rust!
```
+
-
+
We're not gonna lie to you: packaging [Scala] is pretty tricky.
Fortunately, there's a third-party project called [`sbt-derivation`][sbt-derivation] that provides some nice helpers, including a handy function called `mkSbtDerivation`, which is a wrapper around Nix's built-in `derivation` function.
For the full flake behind this package, see [`flake.nix`][flake-scala] on GitHub or run `cat flake.nix`.
To run the resulting package, which is an executable that prints to the terminal:
-```shell
+```shell title="Run the built executable"
./result/bin/zero-to-nix-scala
```
diff --git a/src/pages/start/5.nix-search.mdx b/src/content/start/5.nix-search.mdx
similarity index 61%
rename from src/pages/start/5.nix-search.mdx
rename to src/content/start/5.nix-search.mdx
index 02aecf80..9f58c598 100644
--- a/src/pages/start/5.nix-search.mdx
+++ b/src/content/start/5.nix-search.mdx
@@ -1,11 +1,12 @@
---
title: Search for Nix packages
-path: /start/nix-search
-summary: [
- "Use the `nix search` command to find packages in [Nixpkgs](/concepts/nixpkgs)",
- "Explore the [search.nixos.org](https://search.nixos.org) web interface",
- "Use the `nix flake show` command to explore packages output by [flakes](/concepts/flakes)",
-]
+order: 5
+summary:
+ [
+ "Use the `nix search` command to find packages in [Nixpkgs](/concepts/nixpkgs)",
+ "Explore the [search.nixos.org](https://search.nixos.org) web interface",
+ "Use the `nix flake show` command to explore packages output by [flakes](/concepts/flakes)",
+ ]
---
One great thing about Nix is that there are *tons* of [packages] available in the [Nix ecosystem][ecosystem] that you can use in [Nix development environments][env], in your [NixOS][nixos] installations, and more.
@@ -20,19 +21,23 @@ The [Nix CLI][nix] has a `search` command that you can use to search the package
Let's start by searching [Nixpkgs], which is where we're mostly likely to find packages we want.
This command will tell us if [cargo] is available in [Nixpkgs]:
-```shell
+```shell title="Search Nixpkgs using cargo as the search term"
nix search "https://flakehub.com/f/NixOS/nixpkgs/*" cargo
```
-
-The first time you run `nix search`, the Nix CLI needs to download the full Nix code contents of [Nixpkgs]—or whichever flake you're searching—and then cache it.
-Future `nix search` runs should be much speedier.
-Furthermore, Nixpkgs is the largest flake in existence and running `nix search` on other flakes should be much faster in general.
+In this command, the `nixpkgs` [flake reference][flake-ref] is shorthand for `github:NixOS/nixpkgs`.
+
+
+ The first time you run `nix search`, the Nix CLI needs to download the full
+ Nix code contents of [Nixpkgs]—or whichever flake you're
+ searching—and then cache it. Future `nix search` runs for Nixpkgs should
+ be much speedier. Furthermore, Nixpkgs is the largest flake in existence and
+ running `nix search` on other flakes should be much faster in general.
This brings up many results of the form `legacyPackages.{system}.{package}`, the first of which should look like this on an Apple Silicon (`aarch64-darwin`) system:
-```shell
+```shell title="Example search result"
* legacyPackages.aarch64-darwin.cargo (1.65.0)
Downloads your Rust project's dependencies and builds your project
```
@@ -40,15 +45,22 @@ This brings up many results of the form `legacyPackages.{system}.{package}`, the
The system attribute [varies](#system-specificity) on other platforms (you may see `x86_64-linux` or something else).
After that first result, you should see many others, including packages like [`cargo-about`][cargo-about] and [`cargo-audit`][cargo-audit].
-
-The `legacyPackages` attribute that you see in the search output is a bit misleading.
-The [packages] prefaced with that aren't "legacy" packages; instead, [Nixpkgs] uses a special `legacyPackages` attribute to output packages instead of the usual `packages` output for reasons laid out [here][legacy-comment].
+
+ The `legacyPackages` attribute that you see in the search output is a bit
+ misleading. The [packages] prefaced with that aren't "legacy" packages;
+ instead, [Nixpkgs] uses a special `legacyPackages` attribute to output
+ packages instead of the usual `packages` output for reasons laid out
+ [here][legacy-comment].
You can also output search results as JSON using the `--json` flag:
-```shell
-nix search nixpkgs cargo --json
+```shell title="Output search results as JSON"
+nix search --json nixpkgs cargo
```
This can be useful if you want to parse the output using a tool like [jq].
@@ -57,33 +69,46 @@ This can be useful if you want to parse the output using a tool like [jq].
The web interface at [search.nixos.org][search] has a few advantages over the [`nix search`](#nix-search-command) command:
-* It enables you to select a release channel for [Nixpkgs], such as [22.11] and [unstable]
-* It enables you to search across a range of [public flakes][public-flakes] beyond Nixpkgs (those flakes are listed [here][flakes-list])
+- It enables you to select a release channel for [Nixpkgs], such as [22.11] and [unstable]
+- It enables you to search across a range of [public flakes][public-flakes] beyond Nixpkgs (those flakes are listed [here][flakes-list])
## Exploring a flake with the `nix flake show` command \{#nix-flake-show}
As an example, let's explore a popular flake for the [Wayland] window system protocol.
-```shell
+```shell title="Display the flake outputs for the nixpkgs-wayland flake"
nix flake show "github:nix-community/nixpkgs-wayland"
```
-
-The first time you run `nix flake show`, the Nix CLI needs to download the full contents of [`nixpkgs-wayland`][nixpkgs-wayland]—or whichever flake you're running `nix flake show` on—and then cache it.
-Future `nix flake show` runs for the same [flake reference][flake-ref] should be much speedier.
+You can also display the outputs as JSON:
+
+```shell title="Display the flake outputs for the nixpkgs-wayland flake as JSON"
+nix flake show --json "github:nix-community/nixpkgs-wayland"
+```
+
+
+ The first time you run `nix flake show`, the Nix CLI needs to download the
+ full contents of [`nixpkgs-wayland`][nixpkgs-wayland]—or whichever flake
+ you're running `nix flake show` on—and then cache it. Future `nix flake
+ show` runs for the same [flake reference][flake-ref] should be much speedier.
-
-Should you use `nix flake show` or `nix search`?
-A good rule of thumb is to always use `nix search` with Nixpkgs and to initially use `nix flake show` with other flakes.
-If the package outputs for `nix flake show` are big enough to be tricky to navigate, use `nix search` for that flake instead.
+
+ Should you use `nix flake show` or `nix search`? A good rule of thumb is to
+ always use `nix search` with Nixpkgs and to initially use `nix flake show`
+ with other flakes. If the package outputs for `nix flake show` are big enough
+ to be tricky to navigate, use `nix search` for that flake instead.
## System specificity
One thing you'll notice about the search output for `nix search`, [search.nixos.org][search], and `nix flake show` is that all the packages listed in the query results are for your current system (`x86_64-linux` for an AMD/Intel Linux system, `aarch64-darwin` for an Apple Silicon system, and so on).
That's because Nix works in a fundamentally [system-specific] way.
-The `cargo` package on a Linux machine is considered a *different package* from `cargo` on a non-Linux system.
+The `cargo` package on a Linux machine is considered a _different package_ from `cargo` on a non-Linux system.
[22.11]: https://github.com/nixOS/nixpkgs/tree/22.11
[cargo]: https://github.com/rust-lang/cargo
diff --git a/src/pages/start/6.init-flake.mdx b/src/content/start/6.init-flake.mdx
similarity index 79%
rename from src/pages/start/6.init-flake.mdx
rename to src/content/start/6.init-flake.mdx
index e230eb73..4d99f1fd 100644
--- a/src/pages/start/6.init-flake.mdx
+++ b/src/content/start/6.init-flake.mdx
@@ -1,10 +1,11 @@
---
title: Turn your project into a flake
-path: /start/init-flake
-summary: [
- "Transform an existing project into a [flake](/concepts/flakes)",
- "Use the flake's [development environment](/concepts/dev-env)"
-]
+order: 6
+summary:
+ [
+ "Transform an existing project into a [flake](/concepts/flakes)",
+ "Use the flake's [development environment](/concepts/dev-env)",
+ ]
---
In some of the previous steps in Zero to Nix you learned about [Nix flakes][flakes] and Nix [development environments][dev-env].
@@ -16,20 +17,20 @@ Turning your own projects into flakes can be somewhat tricky, so we at [Determin
You can run `fh init` using Nix:
-```shell
+```shell title="Initialize your flake"
nix run "https://flakehub.com/f/DeterminateSystems/fh/*" -- init
```
This will start up an interactive builder that asks you a series of questions and then writes a `flake.nix` file into the root of your project (plus some other files if you say yes to some of those questions).
Once you've generated a new flake, you can see which outputs it has:
-```shell
+```shell title="Display the flake's outputs"
nix flake show
```
You should see something like this:
-```
+```text title="Flake outputs"
git+file:///path/to/fh-init-example-project
├───devShells
│ ├───aarch64-darwin
@@ -49,17 +50,23 @@ If you say yes, then the generated `flake.nix` will include the `cargo` build to
Note that `fh init` currently only supports [`devShells`][dev-env] outputs.
That is, it only generates a development environment for you, not things like [package outputs][packages].
-
-Be aware that `fh init` operates on a "best-guess" basis to infer which languages and tools you use in your project.
-It's possible that it will miss things or make incorrect guesses.
-But we hope that the `flake.nix` that it creates for you will at least serve as a solid initial template that you can modify further.
+
+ Be aware that `fh init` operates on a "best-guess" basis to infer which
+ languages and tools you use in your project. It's possible that it will miss
+ things or make incorrect guesses. But we hope that the `flake.nix` that it
+ creates for you will at least serve as a solid initial template that you can
+ modify further.
## Example project
We've created an example project that you can use to test out `fh init`:
-```shell
+```shell title="Test out fh init using the example project"
git clone https://github.com/DeterminateSystems/fh-init-example-project
cd fh-init-example-project
nix run "https://flakehub.com/f/DeterminateSystems/fh/*" -- init
diff --git a/src/pages/start/7.uninstall.mdx b/src/content/start/7.uninstall.mdx
similarity index 73%
rename from src/pages/start/7.uninstall.mdx
rename to src/content/start/7.uninstall.mdx
index 84ae9596..f4d3a88f 100644
--- a/src/pages/start/7.uninstall.mdx
+++ b/src/content/start/7.uninstall.mdx
@@ -1,29 +1,27 @@
---
title: Uninstall Nix (if necessary)
-path: /start/uninstall
-summary: [
- "Cleanly remove Nix from your system"
-]
+order: 7
+summary: ["Cleanly remove Nix from your system"]
---
At the beginning of the Zero to Nix quick start, we [installed] Nix using the fast and stable [Determinate Nix Installer][nix-installer], from [Determinate Systems][ds].
We hope that your journey with Nix continues well into the future, but if you need to uninstall Nix for any reason you can do so with this command:
-```shell
+```shell title="Uninstall Nix"
/nix/nix-installer uninstall
```
Follow the prompts to approve the requested changes.
Some of the changes that the installer requests:
-* Delete the directory tree under `/nix`
-* Delete the [Nix] CLI tool
-* Delete all Nix-specific users and groups
-* Delete the Nix configuration file at `/etc/nix/nix.conf`
+- Delete the directory tree under `/nix`
+- Delete the [Nix] CLI tool
+- Delete all Nix-specific users and groups
+- Delete the Nix configuration file at `/etc/nix/nix.conf`
Once the Determinate Nix Installer is done, you can verify that uninstallation has succeeded by confirming that directories like `/nix` and `~/.nix-profile` have been removed from your system:
-```shell
+```shell title="Verify that uninstallation has succeeded"
ls /nix # error
ls ~/.nix-profile # error
```
diff --git a/src/content/start/8.learn-more.mdx b/src/content/start/8.learn-more.mdx
new file mode 100644
index 00000000..7f4de48c
--- /dev/null
+++ b/src/content/start/8.learn-more.mdx
@@ -0,0 +1,187 @@
+---
+title: Learn more
+order: 8
+---
+
+This completes your Zero to Nix journey!
+You just accomplished a great deal:
+
+- You [installed Nix][install] on your machine
+- You ran some [programs] using Nix
+- You explored some [Nix development environments][env]
+- You [searched] for packages in [Nixpkgs] and elsewhere in the Nix [ecosystem]
+- You built some [Nix packages][pkg]
+
+And that's just to name a few.
+We're thrilled that you've taken the time and made the effort.
+But we hope that your Nix journey continues onward.
+This guide suggests some areas beyond the scope of the quick start where you can apply your newly won Nix knowledge.
+
+## Build container images \{#containers}
+
+[Nix] can build [packages] for many things, from standard tools like [curl] and [Git] to [Vim] plugins to [Visual Studio Code][code] extensions to web services that you write in your preferred language and far beyond.
+We've covered a few of these package types here in the [quick start][start].
+Another powerful Nix feature is that you can use it to build [OCI]-compliant container images and thereby replace tools like [Docker] and [Podman] (at least when it comes to building images).
+
+
+
+## Use NixOS as your operating system \{#nixos}
+
+[NixOS] is a [Linux] distribution built on Nix and its core principles, such as [reproducibility] and [declarative configuration][declarative].
+
+
+
+## Configure your home environment \{#home-environment}
+
+[Home Manager][home] is a plugin-based tool built on Nix that you can use to configure a wide range of tools in your home environment, including [Vim], [tmux], [Visual Studio Code][code], [Git], [gpg], and shells like [Bash], [zsh], and [fish].
+
+
+
+## Continuous integration \{#ci}
+
+You learned about [Nix development environments][env] earlier in the quick start.
+Because Nix development environments are both cross platform and fully [reproducible][reproducibility], they're quite useful in [continuous integration][ci] environments.
+
+
+
+[bash]: https://gnu.org/software/bash
+[ci]: https://en.wikipedia.org/wiki/Continuous_integration
+[code]: https://code.visualstudio.com
+[curl]: https://curl.se
+[declarative]: /concepts/declarative
+[docker]: https://docker.com
+[ecosystem]: /concepts/ecosystem
+[env]: /start/nix-develop
+[fish]: https://fishshell.com
+[git]: https://git-scm.com
+[gpg]: https://gnupg.org
+[home]: https://github.com/nix-community/home-manager
+[install]: /start/install
+[linux]: https://www.kernel.org/
+[nix]: /concepts/nix
+[nixos]: /concepts/nixos
+[nixpkgs]: /concepts/nixpkgs
+[oci]: https://opencontainers.org
+[packages]: /concepts/packages
+[pkg]: /start/nix-build
+[programs]: /start/nix-run
+[podman]: https://podman.io
+[reproducibility]: /concepts/reproducibility
+[searched]: /start/nix-search
+[start]: /start
+[tmux]: https://github.com/tmux/tmux
+[vim]: https://www.vim.org
+[zsh]: https://zsh.org
diff --git a/src/entrypoint.ts b/src/entrypoint.ts
new file mode 100644
index 00000000..b2281f75
--- /dev/null
+++ b/src/entrypoint.ts
@@ -0,0 +1,6 @@
+import persist from "@alpinejs/persist";
+import type { Alpine } from "alpinejs";
+
+export default (Alpine: Alpine) => {
+ Alpine.plugin(persist);
+};
diff --git a/src/env.d.ts b/src/env.d.ts
new file mode 100644
index 00000000..851bcd44
--- /dev/null
+++ b/src/env.d.ts
@@ -0,0 +1,12 @@
+///
+///
+
+import type { PostHog } from "posthog-js";
+
+declare global {
+ interface Window {
+ posthog: PostHog;
+
+ Alpine: import('alpinejs').Alpine;
+ }
+}
diff --git a/src/layouts/Layout.astro b/src/layouts/Layout.astro
new file mode 100644
index 00000000..39917d96
--- /dev/null
+++ b/src/layouts/Layout.astro
@@ -0,0 +1,48 @@
+---
+import Banner from "../components/Banner.astro";
+import CookieConsent from "../components/CookieConsent.astro";
+import Footer from "../components/Footer.astro";
+import Head from "../components/Head.astro";
+import Navbar from "../components/Navbar.astro";
+import "../assets/css/main.css";
+import { site } from "../site";
+
+type Props = {
+ title?: string;
+ description?: string;
+};
+
+const { defaultLanguage } = site;
+
+const { title, description } = Astro.props;
+---
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/src/layouts/base.vue b/src/layouts/base.vue
deleted file mode 100644
index c4ae5cb8..00000000
--- a/src/layouts/base.vue
+++ /dev/null
@@ -1,51 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/src/layouts/concepts.vue b/src/layouts/concepts.vue
deleted file mode 100644
index fe3e3867..00000000
--- a/src/layouts/concepts.vue
+++ /dev/null
@@ -1,50 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/src/pages/start/8.learn-more.mdx b/src/pages/start/8.learn-more.mdx
deleted file mode 100644
index 58759be6..00000000
--- a/src/pages/start/8.learn-more.mdx
+++ /dev/null
@@ -1,175 +0,0 @@
----
-title: Learn more
-path: /start/learn-more
----
-
-This completes your Zero to Nix journey!
-You just accomplished a great deal:
-
-* You [installed Nix][install] on your machine
-* You ran some [programs] using Nix
-* You explored some [Nix development environments][env]
-* You [searched] for packages in [Nixpkgs] and elsewhere in the Nix [ecosystem]
-* You built some [Nix packages][pkg]
-
-And that's just to name a few.
-We're thrilled that you've taken the time and made the effort.
-But we hope that your Nix journey continues onward.
-This guide suggests some areas beyond the scope of the quick start where you can apply your newly won Nix knowledge.
-
-## Build container images \{#containers}
-
-[Nix] can build [packages] for many things, from standard tools like [curl] and [Git] to [Vim] plugins to [Visual Studio Code][code] extensions to web services that you write in your preferred language and far beyond.
-We've covered a few of these package types here in the [quick start][start].
-Another powerful Nix feature is that you can use it to build [OCI]-compliant container images and thereby replace tools like [Docker] and [Podman] (at least when it comes to building images).
-
-
-
-
-## Use NixOS as your operating system \{#nixos}
-
-[NixOS] is a [Linux] distribution built on Nix and its core principles, such as [reproducibility] and [declarative configuration][declarative].
-
-
-
-## Configure your home environment \{#home-environment}
-
-[Home Manager][home] is a plugin-based tool built on Nix that you can use to configure a wide range of tools in your home environment, including [Vim], [tmux], [Visual Studio Code][code], [Git], [gpg], and shells like [Bash], [zsh], and [fish].
-
-
-
-## Continuous integration \{#ci}
-
-You learned about [Nix development environments][env] earlier in the quick start.
-Because Nix development environments are both cross platform and fully [reproducible][reproducibility], they're quite useful in [continuous integration][ci] environments.
-
-
-
-[bash]: https://gnu.org/software/bash
-[ci]: https://en.wikipedia.org/wiki/Continuous_integration
-[code]: https://code.visualstudio.com
-[curl]: https://curl.se
-[declarative]: /concepts/declarative
-[docker]: https://docker.com
-[ecosystem]: /concepts/ecosystem
-[env]: /start/nix-develop
-[fish]: https://fishshell.com
-[git]: https://git-scm.com
-[gpg]: https://gnupg.org
-[home]: https://github.com/nix-community/home-manager
-[install]: /start/install
-[linux]: https://www.kernel.org/
-[nix]: /concepts/nix
-[nixos]: /concepts/nixos
-[nixpkgs]: /concepts/nixpkgs
-[oci]: https://opencontainers.org
-[packages]: /concepts/packages
-[pkg]: /start/nix-build
-[programs]: /start/nix-run
-[podman]: https://podman.io
-[reproducibility]: /concepts/reproducibility
-[searched]: /start/nix-search
-[start]: /start
-[tmux]: https://github.com/tmux/tmux
-[vim]: https://www.vim.org
-[zsh]: https://zsh.org
diff --git a/src/pages/start/[slug].astro b/src/pages/start/[slug].astro
new file mode 100644
index 00000000..5b431cf9
--- /dev/null
+++ b/src/pages/start/[slug].astro
@@ -0,0 +1,82 @@
+---
+import type { GetStaticPaths } from "astro";
+import { getCollection } from "astro:content";
+import Admonition from "../../components/mdx/Admonition.astro";
+import ExternalSources from "../../components/ExternalSources.astro";
+import Language from "../../components/mdx/Language.astro";
+import Languages from "../../components/mdx/Languages.astro";
+import Layout from "../../layouts/Layout.astro";
+import NixDevelop from "../../components/mdx/NixDevelop.astro";
+import NixStorePath from "../../components/mdx/NixStorePath.astro";
+import Shell from "../../components/mdx/Shell.astro";
+import SpecificLanguage from "../../components/mdx/SpecificLanguage.astro";
+import HorizontalContainer from "../../components/HorizontalContainer.astro";
+import Hero from "../../components/Hero.astro";
+import Summary from "../../components/Summary.astro";
+import H2 from "../../components/mdx/H2.astro";
+import H3 from "../../components/mdx/H3.astro";
+import H4 from "../../components/mdx/H4.astro";
+import Pagination from "../../components/Pagination.astro";
+import Separator from "../../components/Separator.astro";
+import FeedbackBar from "../../components/FeedbackBar.astro";
+
+export const getStaticPaths = (async () => {
+ const startPages = await getCollection("start");
+
+ return startPages.map((page) => ({
+ params: { slug: page.slug.substring(1) },
+ props: { page },
+ }));
+}) satisfies GetStaticPaths;
+
+const { page } = Astro.props;
+const {
+ data: { title, summary, order },
+} = page;
+const { Content } = await page.render();
+
+const numQuickStartPages = (await getCollection("start")).length;
+---
+
+
+
+
+
+
+ {summary && summary.length > 0 && }
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/src/pages/start/index.astro b/src/pages/start/index.astro
new file mode 100644
index 00000000..bda79907
--- /dev/null
+++ b/src/pages/start/index.astro
@@ -0,0 +1,35 @@
+---
+import { getCollection } from "astro:content";
+import Layout from "../../layouts/Layout.astro";
+import Hero from "../../components/Hero.astro";
+import HorizontalContainer from "../../components/HorizontalContainer.astro";
+import Grid2 from "../../components/Grid2.astro";
+import HoverableLink from "../../components/HoverableLink.astro";
+import { startPagePath } from "../../lib/utils";
+
+const title = "Start";
+const heroTitle = "Quick start";
+const description =
+ "Get a taste of Nix's power and learn key concepts along the way";
+
+const startPages = await getCollection("start");
+---
+
+
+
+
+
+
+ {
+ startPages.map(({ slug, data: { title, order } }) => (
+
+ ))
+ }
+
+
+
diff --git a/src/pages/start/index.vue b/src/pages/start/index.vue
deleted file mode 100644
index ae3e4fae..00000000
--- a/src/pages/start/index.vue
+++ /dev/null
@@ -1,28 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
diff --git a/src/plugins/code.ts b/src/plugins/code.ts
deleted file mode 100644
index 0bf01f7e..00000000
--- a/src/plugins/code.ts
+++ /dev/null
@@ -1,106 +0,0 @@
-import { IlesModule } from "iles";
-import { Code, Root } from "mdast";
-import prism from "prismjs";
-import type { Grammar } from "prismjs";
-import loadLanguages from "prismjs/components/index.js";
-import { Plugin } from "unified";
-import { SKIP, visit } from "unist-util-visit";
-
-// The îles module (add to the `modules` list in the îles config)
-const CodeBlocks = (config: CodeBlockConfig): IlesModule => {
- return {
- name: "code-blocks",
- markdown: {
- remarkPlugins: [[codeBlockPlugin, config]],
- },
- };
-};
-
-// Plugin config
-export interface CodeBlockConfig {
- aliases?: Record;
-}
-
-// Meta fields
-type Meta = {
- filename?: string; // filename=hello.txt
-};
-
-// Parse metadata from a string into a Meta object
-const parseMeta = (s: string): Meta => {
- let meta: Meta = {};
- const segments: string[] = s.split(" ");
- const maybeFilename = segments.find((seg) => seg.startsWith("filename"));
- if (maybeFilename !== undefined) {
- const filename = maybeFilename.split("=").at(1);
- if (filename === undefined) {
- throw new Error(
- "Malformed code block; you need to specify a filename like this: filename=foo.txt",
- );
- } else {
- meta.filename ||= filename;
- }
- }
- return meta;
-};
-
-const highlightCode = (
- code: string,
- grammar: Grammar,
- lang: string,
- meta: string,
-): string => {
- code = prism.highlight(code, grammar, lang);
- const cls = `language-${lang}`;
- const dataLang = lang === "text" ? "" : lang;
- const blockMeta = parseMeta(meta);
- const innerHtml = [
- `