Docs: Getting Started and Quickstart updates - #639
Conversation
|
Azure Static Web Apps: Your stage site is ready! Visit it here: https://lemon-wave-085522403-639.westeurope.1.azurestaticapps.net |
1 similar comment
|
Azure Static Web Apps: Your stage site is ready! Visit it here: https://lemon-wave-085522403-639.westeurope.1.azurestaticapps.net |
There was a problem hiding this comment.
Pull request overview
This PR refreshes the “Getting Started” documentation by simplifying the overview page and expanding the Quickstart into two provisioning paths (virtualized QEMU and bare metal), both using a shared Butane→Ignition example to start an NGINX container via systemd.
Changes:
- Rewrites the Quickstart into “Common Prerequisites” plus separate “Virtualization” and “Bare Metal” walkthroughs.
- Simplifies the Getting Started landing page to focus on core concepts and point readers to the Quickstart and Learning Series.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| content/docs/latest/getting-started/quickstart.md | Restructures and expands the quickstart into virtualization + bare metal paths with shared prerequisites and a Butane/Ignition example. |
| content/docs/latest/getting-started/_index.md | Replaces the long walkthrough with a concise introduction and links to key learning resources and concept docs. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
Azure Static Web Apps: Your stage site is ready! Visit it here: https://lemon-wave-085522403-639.westeurope.1.azurestaticapps.net |
|
Azure Static Web Apps: Your stage site is ready! Visit it here: https://lemon-wave-085522403-639.westeurope.1.azurestaticapps.net |
|
Azure Static Web Apps: Your stage site is ready! Visit it here: https://lemon-wave-085522403-639.westeurope.1.azurestaticapps.net |
|
Azure Static Web Apps: Your stage site is ready! Visit it here: https://lemon-wave-085522403-639.westeurope.1.azurestaticapps.net |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.
Suppressed comments (3)
content/docs/latest/getting-started/_index.md:4
- Front matter uses
content-type, but the rest of the docs consistently usecontent_type(underscore). With the current key, any site logic that relies oncontent_typewill not see this page’s value.
title: Getting Started with Flatcar Container Linux
content-type: explanation
linktitle: Getting Started
content/docs/latest/getting-started/quickstart.md:230
- The
noteshortcode close tag and the next section header are on the same line ({{</note>}} **ARM64 (UEFI):**). This is the only occurrence of that pattern in the docs and can confuse Markdown/shortcode rendering; put the header on its own line after the note block.
{{<note>}} Hosts other than macOS will see
`qemu-system-x86_64: invalid accelerator hvf` followed by a message about
falling back to another accelerator. `hvf` is a macOS-only accelerator, and QEMU
will accommodate automatically and the VM will boot and run normally.
{{</note>}} **ARM64 (UEFI):**
content/docs/latest/getting-started/quickstart.md:17
- PR description says the Quickstart now covers two paths (QEMU and bare metal), but this page currently states it’s QEMU-only and redirects bare-metal readers to a separate doc. Either update the PR description to match the content, or add the promised bare-metal path/sections here.
This quickstart shows how to provision Flatcar Container Linux to run on a local
QEMU virtual machine, and does not require a physical target machine or spare
disk as needed for a bare metal installation. For bare metal provisioning, see
[Installing to disk](../deploy/bare-metal/installing-to-disk).
Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>
…tcar/flatcar-website into bruce/getting-started-update
|
Azure Static Web Apps: Your stage site is ready! Visit it here: https://lemon-wave-085522403-639.westeurope.1.azurestaticapps.net |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.
Suppressed comments (2)
content/docs/latest/getting-started/_index.md:3
- Front matter uses
content-type, but this docs section consistently usescontent_type(underscore). Using the wrong key may cause the page to be misclassified or the metadata to be ignored.
content-type: explanation
content/docs/latest/getting-started/quickstart.md:17
- PR description says the Quickstart now covers two paths (QEMU and bare metal) with shared prerequisite/provisioning sections, but the updated Quickstart page documents only the QEMU VM flow and redirects bare metal users to a separate page. Either expand this doc to include the promised bare-metal path, or update the PR description/scope to match the implemented content.
This quickstart shows how to provision Flatcar Container Linux to run on a local
QEMU virtual machine, and does not require a physical target machine or spare
disk as needed for a bare metal installation. For bare metal provisioning, see
[Installing to disk](../deploy/bare-metal/installing-to-disk).
Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>
|
Azure Static Web Apps: Your stage site is ready! Visit it here: https://lemon-wave-085522403-639.westeurope.1.azurestaticapps.net |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.
Suppressed comments (1)
content/docs/latest/getting-started/_index.md:3
- Front matter uses
content-type, but the docs consistently usecontent_type(underscore). Keeping the hyphenated key risks this page being missed by any logic that readscontent_type.
content-type: explanation
|
Reviewer edits incorporated - ok to merge |
|
Azure Static Web Apps: Your stage site is ready! Visit it here: https://lemon-wave-085522403-639.westeurope.1.azurestaticapps.net |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.
Suppressed comments (2)
content/docs/latest/getting-started/quickstart.md:17
- The PR description says the Quickstart now covers two paths (QEMU virtualization and bare metal) with shared prerequisite/provisioning sections, but this document currently only walks through QEMU deployment and just links out for bare metal. Either update the PR description to match the actual scope, or add/structure the bare metal quickstart steps here as described.
This quickstart shows how to provision Flatcar Container Linux to run on a local
QEMU virtual machine, and does not require a physical target machine or spare
disk as needed for a bare metal installation. For bare metal provisioning, see
[Installing to disk](../deploy/bare-metal/installing-to-disk).
content/docs/latest/getting-started/_index.md:4
- Front matter key uses
content-type, but other docs pages usecontent_type(underscore). Using the wrong key may cause the page to be misclassified/ignored by templates expectingcontent_type(e.g., content/docs/latest/_index.md and fb-provision/butane/_index.md).
title: Getting Started with Flatcar Container Linux
content-type: explanation
linktitle: Getting Started
Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>
|
Azure Static Web Apps: Your stage site is ready! Visit it here: https://lemon-wave-085522403-639.westeurope.1.azurestaticapps.net |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.
Suppressed comments (3)
content/docs/latest/getting-started/quickstart.md:231
- The closing
{{</note>}}and the subsequent**ARM64 (UEFI):**label are on the same line, which can cause the bold label to render as part of the note or get glued to the note HTML without spacing. Put the ARM64 label on its own line after the note block.
{{<note>}} Hosts other than macOS will see
`qemu-system-x86_64: invalid accelerator hvf` followed by a message about
falling back to another accelerator. `hvf` is a macOS-only accelerator, and QEMU
will accommodate automatically and the VM will boot and run normally.
{{</note>}} **ARM64 (UEFI):**
content/docs/latest/getting-started/_index.md:4
- Front matter uses
content-type, but the rest of the docs usecontent_type(underscore). With the hyphenated key, Hugo/site tooling likely won’t see the intended content type for this page.
---
title: Getting Started with Flatcar Container Linux
content-type: explanation
linktitle: Getting Started
content/docs/latest/getting-started/quickstart.md:17
- PR description says the Quickstart now covers two paths (QEMU and bare metal) with shared prerequisite/provisioning sections, but the updated quickstart content only documents the QEMU path and merely links to the bare metal install docs. Either expand this page to include the described bare metal path/sections, or adjust the PR description to match what’s actually changed.
This quickstart shows how to provision Flatcar Container Linux to run on a local
QEMU virtual machine, and does not require a physical target machine or spare
disk as needed for a bare metal installation. For bare metal provisioning, see
[Installing to disk](../deploy/bare-metal/installing-to-disk).
|
Azure Static Web Apps: Your stage site is ready! Visit it here: https://lemon-wave-085522403-639.westeurope.1.azurestaticapps.net |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.
Suppressed comments (2)
content/docs/latest/getting-started/_index.md:3
- Front matter uses
content-type, but the rest of the docs usecontent_type(underscore). With the hyphenated key Hugo will treat this as an unknown param, which may break any logic expectingcontent_type.
content-type: explanation
content/docs/latest/getting-started/quickstart.md:17
- PR description says the Quickstart is updated to cover two paths (QEMU and bare metal), but the current page only contains QEMU deployment steps and just links out to bare metal installation. Either add the promised bare-metal path here or update the PR description to match the actual scope.
This quickstart shows how to provision Flatcar Container Linux to run on a local
QEMU virtual machine, and does not require a physical target machine or spare
disk as needed for a bare metal installation. For bare metal provisioning, see
[Installing to disk](../deploy/bare-metal/installing-to-disk).
|
Azure Static Web Apps: Your stage site is ready! Visit it here: https://lemon-wave-085522403-639.westeurope.1.azurestaticapps.net |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
Suppressed comments (1)
content/docs/latest/getting-started/quickstart.md:17
- PR description says the Quickstart “covers two paths: Virtualization via QEMU and bare metal”, but the updated quickstart page only documents the QEMU path and links out to the bare-metal install guide. Either expand this page to include the bare-metal path/sections as described, or adjust the PR description to match the actual scope.
This quickstart shows how to provision Flatcar Container Linux to run on a local
QEMU virtual machine, and does not require a physical target machine or spare
disk as needed for a bare metal installation. For bare metal provisioning, see
[Installing to disk](../deploy/bare-metal/installing-to-disk).
Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>
|
Azure Static Web Apps: Your stage site is ready! Visit it here: https://lemon-wave-085522403-639.westeurope.1.azurestaticapps.net |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.
Suppressed comments (2)
content/docs/latest/getting-started/quickstart.md:230
- The note about the
hvfaccelerator is phrased as something non-macOS hosts “will see”, and the closing shortcode shares a line with the next section heading. This makes the statement overly absolute and is the only instance in the docs where{{</note>}}is followed by other content, which can be fragile for Hugo shortcode parsing.
{{<note>}} Hosts other than macOS will see
`qemu-system-x86_64: invalid accelerator hvf` followed by a message about
falling back to another accelerator. `hvf` is a macOS-only accelerator, and QEMU
will accommodate automatically and the VM will boot and run normally.
{{</note>}} **ARM64 (UEFI):**
content/docs/latest/getting-started/quickstart.md:17
- The PR description says the Quickstart is updated to cover two paths (QEMU and bare metal) with shared “common prerequisites”/“common provisioning tasks” sections, but this page currently only walks through the QEMU path and links out for bare metal. Please align the PR description with the actual content, or add the promised bare-metal path/structure here.
This quickstart shows how to provision Flatcar Container Linux to run on a local
QEMU virtual machine, and does not require a physical target machine or spare
disk as needed for a bare metal installation. For bare metal provisioning, see
[Installing to disk](../deploy/bare-metal/installing-to-disk).
|
Azure Static Web Apps: Your stage site is ready! Visit it here: https://lemon-wave-085522403-639.westeurope.1.azurestaticapps.net |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
Suppressed comments (1)
content/docs/latest/getting-started/quickstart.md:233
- This code block uses a single long command with
&&, while the AMD64 example uses one command per line. Splitting it into separate lines improves readability and copy/paste behavior.
cp flatcar_production_qemu_uefi_image.img.fresh flatcar_production_qemu_uefi_image.img && ./flatcar_production_qemu_uefi.sh -i ignition.json
Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>
|
Azure Static Web Apps: Your stage site is ready! Visit it here: https://lemon-wave-085522403-639.westeurope.1.azurestaticapps.net |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.
Suppressed comments (4)
Previously missed (2) — in code that hasn't changed since the last review.
content/docs/latest/getting-started/quickstart.md:17
- The relative link to the bare-metal install guide is off by one directory level. From
/getting-started/quickstart/,../deploy/...resolves under/getting-started/and will 404; it should go up to/docs/latest/first.
This issue also appears on line 58 of the same file.
QEMU virtual machine, and does not require a physical target machine or spare
disk as needed for a bare metal installation. For bare metal provisioning, see
[Installing to disk](../deploy/bare-metal/installing-to-disk).
content/docs/latest/getting-started/quickstart.md:21
- The Butane and Ignition links are using
../from the Quickstart page, which will resolve under/getting-started/in the rendered site URL. These should be../../to correctly link to the sibling/fb-provision/section.
YAML, and then runs [Butane](../fb-provision/butane/) to transpile it into a
JSON file for use by [Ignition](../fb-provision/ignition/boot-process) in the
content/docs/latest/getting-started/quickstart.md:59
- The QEMU documentation link is off by one directory level (
../deploy/...will resolve under/getting-started/). Use../../deploy/...so it points at the top-level Deployments section.
Install [QEMU](../deploy/virt-options/qemu), a generic and open-source machine
emulator and virtualizer.
content/docs/latest/getting-started/quickstart.md:16
- PR description says the Quickstart now covers two paths (QEMU and bare metal), but the updated page still describes only the QEMU VM workflow and merely links out to the bare-metal install guide. Either the PR description should be updated to match the actual scope, or this page should add the promised bare-metal path/sections.
This quickstart shows how to provision Flatcar Container Linux to run on a local
QEMU virtual machine, and does not require a physical target machine or spare
disk as needed for a bare metal installation. For bare metal provisioning, see
Updated Getting Started and Quickstart
This PR updates the _index.md overview page to introduced core concepts and ink to the Quickstart and Learning Series.
The Quickstart is updated to cover two paths: Virtualization via QEMU and bare metal.
They share and reference a "common prerequisites" and "common provisioning tasks" sections.
The argument can be made for separating the quickstart into two topics, but I think it has its advantages.
Copilot assisted me. Ready for human tech review.