From 0395a916623b92c75e519527a45f323339486907 Mon Sep 17 00:00:00 2001 From: Tulip Blossom Date: Mon, 9 Dec 2024 18:01:04 -0300 Subject: [PATCH] feat: sorted sidebar + move everything over --- docs/Documentation/introduction.md | 181 ------------------ docs/{Documentation => }/FAQ.md | 2 +- docs/{Documentation => }/administration.md | 0 docs/{Documentation => }/ai.md | 0 docs/{Documentation => }/bluefin-dx.md | 0 docs/{Contributing => }/contributing.md | 1 + .../{Supporting The Project => }/donations.md | 0 docs/{Framework Laptops => }/framework-13.md | 0 docs/{Framework Laptops => }/framework-16.md | 0 docs/{Framework Laptops => }/framework.md | 0 docs/{Contributing => }/local.md | 0 docs/{Documentation => }/press-kit.md | 0 docs/{T2 Macs (2018-2020) => }/t2-mac.md | 0 docs/{Documentation => }/tips.md | 0 docusaurus.config.ts | 7 +- sidebars.ts | 53 +++-- 16 files changed, 47 insertions(+), 197 deletions(-) delete mode 100644 docs/Documentation/introduction.md rename docs/{Documentation => }/FAQ.md (98%) rename docs/{Documentation => }/administration.md (100%) rename docs/{Documentation => }/ai.md (100%) rename docs/{Documentation => }/bluefin-dx.md (100%) rename docs/{Contributing => }/contributing.md (99%) rename docs/{Supporting The Project => }/donations.md (100%) rename docs/{Framework Laptops => }/framework-13.md (100%) rename docs/{Framework Laptops => }/framework-16.md (100%) rename docs/{Framework Laptops => }/framework.md (100%) rename docs/{Contributing => }/local.md (100%) rename docs/{Documentation => }/press-kit.md (100%) rename docs/{T2 Macs (2018-2020) => }/t2-mac.md (100%) rename docs/{Documentation => }/tips.md (100%) diff --git a/docs/Documentation/introduction.md b/docs/Documentation/introduction.md deleted file mode 100644 index 836d152..0000000 --- a/docs/Documentation/introduction.md +++ /dev/null @@ -1,181 +0,0 @@ ---- -title: Introduction to Bluefin -slug: /introduction ---- - -![image](https://github.com/user-attachments/assets/21208dd6-9ce5-41ba-9c21-d2bb97f7c1e8) - -# Features - -System updates are image-based and automatic. Applications are logically separated from the system by using Flatpaks for graphical applications and `brew` for command line applications. - -> Bluefin is also "An interpretation of the Ubuntu spirit built on Fedora technology", which is a certain era of Ubuntu's history that a significant amount of open source people grew up with, like the Classic X-men. We try to bring that vibe here, we're the reboot. Chill vibes. - -- Ubuntu-like GNOME layout. - - Integrates the following GNOME Extensions by default: - - [Dash to Dock](https://micheleg.github.io/dash-to-dock/) - for a more Unity-like dock - - [Appindicator](https://github.com/ubuntu/gnome-shell-extension-appindicator) - for tray-like icons in the top right corner - - [GSConnect](https://github.com/GSConnect/gnome-shell-extension-gsconnect) - Integrate your mobile device with your desktop - - [Blur my Shell](https://github.com/aunetx/blur-my-shell) - for that bling - - [Tailscale GNOME QS](https://extensions.gnome.org/extension/6139/tailscale-qs/) for [tailscale integration](https://universal-blue.discourse.group/t/tailscale-vpn/290) - - [Search Light](https://github.com/icedman/search-light) - for search and a MacOS Spotlight workflow. Bound to Super-Space by default -- [Developer Mode](bluefin-dx) - Dedicated developer mode that transforms Bluefin into a powerful cloud native developer workstation. -- [Ptyxis terminal](https://devsuite.app/ptyxis/) for container-focused workflows - - [Boxbuddy](https://flathub.org/apps/io.github.dvlv.boxbuddyrs) for container management -- [Tailscale](https://tailscale.com) - included for VPN along with `wireguard-tools` - - Use `ujust toggle-tailscale` to turn it off if you don't plan on using it. -- [GNOME Extensions Manager](https://flathub.org/apps/com.mattjakeman.ExtensionManager) included -- GNOME Software with [Flathub](https://flathub.org): - - Use a familiar software center UI to install graphical software - - [Warehouse](https://flathub.org/apps/io.github.flattool.Warehouse) included for flatpak management -- Quality of Life Features - - [Starship](https://starship.rs) terminal prompt enabled by default - - [Input Leap](https://github.com/input-leap/input-leap) built in - - [Solaar](https://github.com/pwr-Solaar/Solaar) - included for Logitech mouse - management along with `libratbagd` - - [rclone](https://rclone.org/) and [restic](https://restic.net/) included - - `zsh` and `fish` included ([Instructions](/administration#changing-the-default-terminal-shell)) -- Built on top of the the [Universal Blue main image](https://github.com/ublue-os/main) - resulting in easy sharing of benefits: - - Extra udev rules for game controllers and [other devices](https://github.com/ublue-os/config) included out of the box - - All multimedia codecs included - - Many improvements from [Bazzite](https://bazzite.gg): GNOME Triple Buffering, Switcheroo support - - System designed for automatic staging of updates - - If you've never used an image-based Linux before just use your computer normally - - Don't overthink it, just shut your computer off when you're not using it - -# Applications - -- Mozilla Firefox, Mozilla Thunderbird, Extension Manager, DejaDup, FontDownloader, Flatseal, and the Clapper Media Player. -- Core GNOME Applications installed from Flathub: - - GNOME Calculator, Calendar, Characters, Connections, Contacts, Evince, Firmware, Logs, Maps, NautilusPreviewer, TextEditor, Weather, baobab, clocks, eog, and font-viewer. - -# Installation Requirements - -Review the [Fedora Silverblue installation instructions](https://docs.fedoraproject.org/en-US/fedora-silverblue/installation/). Some points to consider: - -- Use the [Fedora Media Writer](https://flathub.org/apps/org.fedoraproject.MediaWriter) to create installation media. Other creation methods may not work properly. -- Dual booting off of the same disk is **unsupported**, use a dedicated drive for another operating system and use your BIOS to choose another OS to boot off of. (This is how you should probably always do it anyway) -- We **strongly recommend** using automated partitioning during installation, there are [known issues](https://docs.fedoraproject.org/en-US/fedora-silverblue/installation/) with manual partition on Atomic systems and is unnecessary to set up unless you are on a multi-disk system. -- A stock Bluefin installation is 11GB. Bluefin with developer mode enabled (`bluefin-dx`) is 19GB. -- Read the installation runbook below to ensure your device and use case are supported by Bluefin! - -In order to set yourself up to success it's useful to plan out your Bluefin installation into three distinct phases, mirroring the systems operations lifecycle. - -# Installation Runbook - -Here is a short [runbook](https://www.pagerduty.com/resources/learn/what-is-a-runbook/) for the Bluefin installation process. Read the entirety of this documentation in order to ensure survival. (In case of a raptor attack). - -## Day 0 - Planning - -Most pain points can be addressed directly by planning ahead of time. - -### All Users - -- Is your hardware Linux friendly? - - Do you understand the limitations of having an Nvidia GPU? (If applicable?) - - Does the hardware require an out of tree kernel module? This may lead to long term maintenance issues. - - Does the software you use require an out of tree kernel module? - - VirtualBox and VMWare are not supported - - Nvidia, Xbox One Controller Support, wl drivers, and v4l2loopback are supported. (These are "best effort", in certain cases we cannot control third party software that breaks with newer versions of the Linux kernel) - - Is your wireless card supported by Linux? - - Poorly supported cards include Broadcom - - Check [USB-Wifi](https://github.com/morrownr/USB-WiFi) if you are not sure - - Is your printer/scanner well supported in Linux? - - [Driverless printers](https://openprinting.github.io/printers/) are strongly recommended, we cannot guarantee every printer will work - - [Scanner support](http://www.sane-project.org/sane-mfgs.html) -- Are the applications you depend on well supported on Flathub? -- Does your VPN provider provide a wireguard configuration to import into Network Manager? -- Dedicated disk ready to go? - - Bluefin does not support dual booting from the same disk - - Bluefin does not support rebasing from a pre-existing installation of Fedora -- Remember that this is a custom Fedora based image, it does move at a brisk pace compared to something like Ubuntu LTS -- Read this documentation in its entirety, here's some associated upstream documentation: - - [Homebrew](https://docs.brew.sh/) - - [Flathub](https://docs.flathub.org/) - - [bootc](https://containers.github.io/bootc/) - - [rpm-ostree](https://coreos.github.io/rpm-ostree/) - this tool is deprecated in Bluefin but still available on the image, it will be removed in Spring 2025 - -### Developers - -- Do you know [how to use containers](https://docker-curriculum.com/#introduction) for development? -- Do you know how to manage [systemd service units](https://systemd.io/) for both the system and user accounts? - -## Day 1 - Deployment and Configuration - -### Deployment - -- Download the right ISO from [the website](https://projectbluefin.io/#scene-picker) -- Install the operating system - - Use the entire disk with automatic partitioning - - (Optional): [Set up Secure Boot](/introduction.md#secure-boot) - - (Optional): `ujust switch-channel` to move to `:stable` or `:latest` -- Set up, test, and **verify backups** - While the system image is reproducible data, your user data in your home folder still needs to be backed up. Bluefin ships with two backup utilities depending on your preference. They are installed as Flatpaks so you can remove the one you don't use. `rclone` and `restic` are also preinstalled if you prefer command line tools - - [Deja Dup](https://apps.gnome.org/DejaDup/) - - [Pika Backup](https://apps.gnome.org/PikaBackup/) - - Ensure your backups are functional _before_ moving on to configuration - -### Configuration - -The rest of these steps are user specific configuration and something that we tend to leave up to you. Automating this step is a good place to use tools like [chezmoi](https://www.chezmoi.io/) for dotfile configuration and syncing: `brew install chezmoi` - -Since the user space is all in your home directory, just about any tool you use to automate this step should work as you expect. Ideally, configuration that you might have done at the system level in the past is configured at your user level now, leading to a clean seperation between user configuration and the system image. - -- Software Installation - - Use GNOME Software to install Flatpaks - - (Optional): Use Flatseal to manage Flatpak permissions if appropriate - - (Optional): Install Command line applications via `brew` -- Post-installation Configuration - - Select/Change default applications as you see fit - - (Optional) Import your [wireguard configuration via `wg-quick`](https://blogs.gnome.org/thaller/2019/03/15/wireguard-in-networkmanager/) or use the VPN configuration in the network manager GUI -- (Optional) Developer Configuration - - `ujust devmode` and follow the directions - - Start VSCode and configure your settings and extensions - -## Day 2 - Operations and Maintenance - -Bluefin strives to make maintenance as easy as possible, however many of the automated tasks can be run manually. - -- Run a System Upgrade via the menu option or `ujust update` to observe an update and reboot - - `ujust changelogs` will show incoming changes and updates coming from Fedora - - `ujust bios` will reboot the machine and enter the BIOS/UEFI menu. This is useful for booting into a Windows drive -- Subscribe to the [announcements tag](https://universal-blue.discourse.group/tag/announcements) on the Universal Blue forums -- Understand [rebase and rollback procedures](/Documentation/administration.md#switching-between-streams) -- Use the [Warehouse application](https://github.com/flattool/warehouse) to manage Flatpak lifecycle: - - Pin to an old version or rollback - - Easily remove applications at once -- `ujust clean-system` to clean up old containers and unused flatpak runtimes - -And one more piece of advice: The more you invest into day 0, the smoother your day 1 will be, which results in an even smoother day 2. After that, it's all bragging rights. The `fastfetch` command will be there to remind you of your milestone: - -![image](https://github.com/user-attachments/assets/e1b77128-6aaf-4a95-a9fc-cb1409a176fc) - -## Secure Boot - -Secure Boot is supported by default providing an additional layer of security. - -Universal Blue supports secure boot with [our custom key](https://github.com/ublue-os/akmods/raw/main/certs/public_key.der) - -After the first installation, you will be prompted to enroll the secure boot key in the mokutil UEFI menu UI (_QWERTY_ keyboard input and navigation). - -Then, select "Enroll MOK", and input "`universalblue`" as the password - -If this step is not completed during the initial setup, you can manually enroll the key by running the following command in the terminal: - -```sh -ujust enroll-secure-boot-key -``` - -If you'd like to enroll this key prior to installation or rebase, download the key and run the following: - -```sh -sudo mokutil --timeout -1 -sudo mokutil --import path/to/public_key.der -``` - -You can use `mokutil --list-enrolled` to confirm that the "ublue kernel" key is listed: - -![image](https://github.com/user-attachments/assets/259a9bb2-2198-4744-924d-df457e26c7f4) - -_If you see `ublue akmods\` listed, it is a former key that is soon to be removed. `ublue kernel` is the current key._ - -[Move on to system administration](administration) diff --git a/docs/Documentation/FAQ.md b/docs/FAQ.md similarity index 98% rename from docs/Documentation/FAQ.md rename to docs/FAQ.md index 20c2b09..06156cd 100644 --- a/docs/Documentation/FAQ.md +++ b/docs/FAQ.md @@ -14,7 +14,7 @@ Everything you need is included. Other than the visual differences, and codecs, there are some other key differences between Bluefin and Fedora Silverblue from a usage perspective: - Bluefin takes a [greenfield approach](https://en.wikipedia.org/wiki/Greenfield_project) to Linux applications by defaulting to Flathub and `brew` by default -- Bluefin doesn't recommend using Toolbx - it instead focuses on [devcontainers](/Documentation/bluefin-dx.md#the-cloud-native-development-approach) for declarative containerized development. +- Bluefin doesn't recommend using Toolbx - it instead focuses on [devcontainers](/bluefin-dx.md#the-cloud-native-development-approach) for declarative containerized development. - Bluefin _tries_ to remove the need for the user to use `rpm-ostree` or `bootc` directly - Bluefin focuses on automation of OS services and upgrades instead of user interaction diff --git a/docs/Documentation/administration.md b/docs/administration.md similarity index 100% rename from docs/Documentation/administration.md rename to docs/administration.md diff --git a/docs/Documentation/ai.md b/docs/ai.md similarity index 100% rename from docs/Documentation/ai.md rename to docs/ai.md diff --git a/docs/Documentation/bluefin-dx.md b/docs/bluefin-dx.md similarity index 100% rename from docs/Documentation/bluefin-dx.md rename to docs/bluefin-dx.md diff --git a/docs/Contributing/contributing.md b/docs/contributing.md similarity index 99% rename from docs/Contributing/contributing.md rename to docs/contributing.md index fc62cda..374c11d 100644 --- a/docs/Contributing/contributing.md +++ b/docs/contributing.md @@ -1,4 +1,5 @@ --- +title: Contributor's guide slug: /contributing --- diff --git a/docs/Supporting The Project/donations.md b/docs/donations.md similarity index 100% rename from docs/Supporting The Project/donations.md rename to docs/donations.md diff --git a/docs/Framework Laptops/framework-13.md b/docs/framework-13.md similarity index 100% rename from docs/Framework Laptops/framework-13.md rename to docs/framework-13.md diff --git a/docs/Framework Laptops/framework-16.md b/docs/framework-16.md similarity index 100% rename from docs/Framework Laptops/framework-16.md rename to docs/framework-16.md diff --git a/docs/Framework Laptops/framework.md b/docs/framework.md similarity index 100% rename from docs/Framework Laptops/framework.md rename to docs/framework.md diff --git a/docs/Contributing/local.md b/docs/local.md similarity index 100% rename from docs/Contributing/local.md rename to docs/local.md diff --git a/docs/Documentation/press-kit.md b/docs/press-kit.md similarity index 100% rename from docs/Documentation/press-kit.md rename to docs/press-kit.md diff --git a/docs/T2 Macs (2018-2020)/t2-mac.md b/docs/t2-mac.md similarity index 100% rename from docs/T2 Macs (2018-2020)/t2-mac.md rename to docs/t2-mac.md diff --git a/docs/Documentation/tips.md b/docs/tips.md similarity index 100% rename from docs/Documentation/tips.md rename to docs/tips.md diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 3a902d0..4928867 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -1,5 +1,5 @@ import { themes as prismThemes } from "prism-react-renderer"; -import type { Config } from "@docusaurus/types"; +import type { Config, SidebarItem } from "@docusaurus/types"; import type * as Preset from "@docusaurus/preset-classic"; // This runs in Node.js - Don't use client-side code here (browser APIs, JSX...) @@ -32,9 +32,8 @@ const config: Config = { sidebarPath: "./sidebars.ts", // Disables the landing page routeBasePath: "/", - // FIXME: Change this into the proper URL editUrl: - "https://github.com/ublue-os/bluefin-docs/tree/main/packages/create-docusaurus/templates/shared/", + "https://github.com/ublue-os/bluefin-docs/tree/main/packages/docs", }, theme: { customCss: "./src/css/custom.css", @@ -71,7 +70,7 @@ const config: Config = { items: [ { type: "docSidebar", - sidebarId: "tutorialSidebar", + sidebarId: "baseSidebar", position: "left", label: "Documentation", }, diff --git a/sidebars.ts b/sidebars.ts index 574ed39..fe9872d 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -13,21 +13,52 @@ import type { SidebarsConfig } from "@docusaurus/plugin-content-docs"; Create as many sidebars as you want. */ const sidebars: SidebarsConfig = { - // By default, Docusaurus generates a sidebar from the docs folder structure - tutorialSidebar: [{ type: "autogenerated", dirName: "." }], - - // But you can create a sidebar manually - /* - tutorialSidebar: [ - 'intro', - 'hello', + baseSidebar: [ + { + type: 'category', + label: 'Documentation', + items: [ + 'introduction', + 'administration', + 'ai', + 'bluefin-dx', + 'tips', + 'FAQ', + 'press-kit' + ] + }, + { + type: 'category', + label: 'Contributing', + items: [ + 'contributing', + 'local', + ] + }, + { + type: 'category', + label: 'Framework Laptops', + items: [ + 'framework', + 'framework-13', + 'framework-16', + ] + }, + { + type: 'category', + label: 'T2 Macs (2018-2020)', + items: [ + 't2-mac', + ] + }, { type: 'category', - label: 'Tutorial', - items: ['tutorial-basics/create-a-document'], + label: 'Supporting The Project', + items: [ + 'donations', + ] }, ], - */ }; export default sidebars;