From 1806c6c16e8412fc97efbafd5df7ad5c6dc510bb Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Sun, 18 May 2025 18:35:11 +0200 Subject: [PATCH] Docs: move 'getting-started' into guides section --- README.md | 2 +- docs/mkdocs.yml | 14 +++++----- .../{ => guides}/getting-started/check.md | 0 .../{ => guides}/getting-started/configure.md | 6 ++--- .../{ => guides}/getting-started/deploy.md | 0 .../{ => guides}/getting-started/index.md | 6 ++--- .../{ => guides}/getting-started/installer.md | 2 +- .../{ => guides}/getting-started/secrets.md | 0 docs/site/index.md | 27 +------------------ docs/site/manual/migration-guide.md | 12 ++++----- docs/site/manual/vars-backend.md | 2 +- reference/cli/index.md | 0 12 files changed, 23 insertions(+), 48 deletions(-) rename docs/site/{ => guides}/getting-started/check.md (100%) rename docs/site/{ => guides}/getting-started/configure.md (95%) rename docs/site/{ => guides}/getting-started/deploy.md (100%) rename docs/site/{ => guides}/getting-started/index.md (98%) rename docs/site/{ => guides}/getting-started/installer.md (99%) rename docs/site/{ => guides}/getting-started/secrets.md (100%) create mode 100644 reference/cli/index.md diff --git a/README.md b/README.md index e3c2dc95b..fe3e33756 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ If you're new to Clan and eager to dive in, start with our quickstart guide and In the Clan ecosystem, security is paramount. Learn how to handle secrets effectively: -- **Secrets Management**: Securely manage secrets by consulting [secrets](https://docs.clan.lol/getting-started/secrets/). +- **Secrets Management**: Securely manage secrets by consulting [secrets](https://docs.clan.lol/guides/getting-started/secrets/). ### Contributing to Clan diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index fef4f9271..3713fcbd2 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -46,14 +46,14 @@ exclude_docs: | nav: - Home: index.md - - Getting Started: - - Setup Clan: getting-started/index.md - - Create Installer: getting-started/installer.md - - Add Machines: getting-started/configure.md - - Secrets & Facts: getting-started/secrets.md - - Deploy Machine: getting-started/deploy.md - - Continuous Integration: getting-started/check.md - Guides: + - Getting Started: + - Setup Clan: guides/getting-started/index.md + - Create Installer: guides/getting-started/installer.md + - Add Machines: guides/getting-started/configure.md + - Secrets & Facts: guides/getting-started/secrets.md + - Deploy Machine: guides/getting-started/deploy.md + - Continuous Integration: guides/getting-started/check.md - clanServices: guides/clanServices.md - Disk Encryption: guides/disk-encryption.md - Mesh VPN: guides/mesh-vpn.md diff --git a/docs/site/getting-started/check.md b/docs/site/guides/getting-started/check.md similarity index 100% rename from docs/site/getting-started/check.md rename to docs/site/guides/getting-started/check.md diff --git a/docs/site/getting-started/configure.md b/docs/site/guides/getting-started/configure.md similarity index 95% rename from docs/site/getting-started/configure.md rename to docs/site/guides/getting-started/configure.md index a44d97887..4c54eb754 100644 --- a/docs/site/getting-started/configure.md +++ b/docs/site/guides/getting-started/configure.md @@ -14,7 +14,7 @@ Clan currently offers the following methods to configure machines: - machines/`machine_name`/configuration.nix (`autoincluded` if it exists) - See the complete [list](../manual/adding-machines.md#automatic-registration) of auto-loaded files. + See the complete [list](../../manual/adding-machines.md#automatic-registration) of auto-loaded files. ???+ Note "Used by CLI & UI" @@ -40,7 +40,7 @@ In the `flake.nix` file: === "**template using flake-parts**" - !!! info "See [Clan with flake-parts](../manual/flake-parts.md) for help migrating to flake-parts." + !!! info "See [Clan with flake-parts](../../manual/flake-parts.md) for help migrating to flake-parts." ```nix title="flake.nix" hl_lines="3" clan = { @@ -106,7 +106,7 @@ Adding or configuring a new machine requires two simple steps: clan.core.networking.targetHost = "root@__IP__"; - # Replace this __CHANGE_ME__ with the result of the lsblk command from step 1. + # Replace this __CHANGE_ME__ with the result of the lsblk command from step 1. disko.devices.disk.main.device = "/dev/disk/by-id/__CHANGE_ME__"; # IMPORTANT! Add your SSH key here diff --git a/docs/site/getting-started/deploy.md b/docs/site/guides/getting-started/deploy.md similarity index 100% rename from docs/site/getting-started/deploy.md rename to docs/site/guides/getting-started/deploy.md diff --git a/docs/site/getting-started/index.md b/docs/site/guides/getting-started/index.md similarity index 98% rename from docs/site/getting-started/index.md rename to docs/site/guides/getting-started/index.md index b113ab4da..a3072e737 100644 --- a/docs/site/getting-started/index.md +++ b/docs/site/guides/getting-started/index.md @@ -45,7 +45,7 @@ Add the Clan CLI into your development workflow: nix shell git+https://git.clan.lol/clan/clan-core#clan-cli --refresh ``` -You can find reference documentation for the `clan` cli program [here](../reference/cli/index.md). +You can find reference documentation for the `clan` cli program [here](../../reference/cli/index.md). Alternatively you can check out the help pages directly: ```terminalSession @@ -104,8 +104,8 @@ This should yield the following: That way you will have the tool available in the shell environment. We also recommend setting up [direnv](https://direnv.net/) for your shell, for a more convenient experience. - - + + ```bash clan machines list diff --git a/docs/site/getting-started/installer.md b/docs/site/guides/getting-started/installer.md similarity index 99% rename from docs/site/getting-started/installer.md rename to docs/site/guides/getting-started/installer.md index 07cfbfb0b..c1dfd7fb8 100644 --- a/docs/site/getting-started/installer.md +++ b/docs/site/guides/getting-started/installer.md @@ -151,7 +151,7 @@ sudo umount /dev/sdb1 ### Step 3: Boot From USB Stick -- To use, boot from the Clan USB drive with **secure boot turned off**. For step by step instructions go to [Disabling Secure Boot](../manual/secure-boot.md) +- To use, boot from the Clan USB drive with **secure boot turned off**. For step by step instructions go to [Disabling Secure Boot](../../manual/secure-boot.md) ## (Optional) Connect to Wifi Manually diff --git a/docs/site/getting-started/secrets.md b/docs/site/guides/getting-started/secrets.md similarity index 100% rename from docs/site/getting-started/secrets.md rename to docs/site/guides/getting-started/secrets.md diff --git a/docs/site/index.md b/docs/site/index.md index 701f5c10d..4ac959d37 100644 --- a/docs/site/index.md +++ b/docs/site/index.md @@ -6,32 +6,7 @@ hide: # :material-home: Welcome to **Clan**'s documentation -[Getting Started](./getting-started/index.md){ .md-button } - -## Tutorials - -**Learning-oriented adventures with a hands-on experience.** - -
- -- :material-clock-fast:{ .lg .middle } __Set up in 15 minutes__ - - --- - - Create your own clan and get everything - running in minutes - - [:octicons-arrow-right-24: Getting started](./getting-started/index.md) - -- :fontawesome-solid-user-group:{ .lg .middle } __Authoring Modules__ - - --- - - Create ressources that can be reused by the community. - - [:octicons-arrow-right-24: Authoring guides](./guides/authoring/clanModules/index.md) - -
+[Getting Started](./guides/getting-started/index.md){ .md-button } ## :material-book: Guides diff --git a/docs/site/manual/migration-guide.md b/docs/site/manual/migration-guide.md index d14637d04..c19c7b7dd 100644 --- a/docs/site/manual/migration-guide.md +++ b/docs/site/manual/migration-guide.md @@ -1,10 +1,10 @@ # Migrate existing NixOS configurations -This guide will help you migrate your existing Nix configurations into Clan. +This guide will help you migrate your existing Nix configurations into Clan. !!! Warning Migrating instead of starting new can be trickier and might lead to bugs or - unexpected issues. We recommend following the [Getting Started](../getting-started/index.md) guide first. Once you have a working setup, you can easily transfer your Nix configurations over. + unexpected issues. We recommend following the [Getting Started](../guides/getting-started/index.md) guide first. Once you have a working setup, you can easily transfer your Nix configurations over. ## Back up your existing configuration! Before you start, it is strongly recommended to back up your existing @@ -77,9 +77,9 @@ For the provide flake example, your flake should now look like this: ```nix { inputs.nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable"; - + inputs.clan-core = { - url = "git+https://git.clan.lol/clan/clan-core"; + url = "git+https://git.clan.lol/clan/clan-core"; inputs.nixpkgs.follows = "nixpkgs"; }; @@ -104,9 +104,9 @@ For the provide flake example, your flake should now look like this: in { nixosConfigurations = clan.nixosConfigurations; - + inherit (clan) clanInternals; - + clan = { inherit (clan) templates; }; diff --git a/docs/site/manual/vars-backend.md b/docs/site/manual/vars-backend.md index 501dd3bb2..eae7ff225 100644 --- a/docs/site/manual/vars-backend.md +++ b/docs/site/manual/vars-backend.md @@ -10,7 +10,7 @@ In this example, we will guide you through automating that interaction using cla For a more general explanation of what clan vars are and how it works, see the intro of the [Reference Documentation for vars](https://docs.clan.lol/reference/clan-core/vars/) This guide assumes -- clan is set up already (see [Getting Started](../getting-started/index.md)) +- clan is set up already (see [Getting Started](../guides/getting-started/index.md)) - a machine has been added to the clan (see [Adding Machines](./adding-machines.md)) This section will walk you through the following steps: diff --git a/reference/cli/index.md b/reference/cli/index.md new file mode 100644 index 000000000..e69de29bb