Repository: ariel-os/ariel-os
Pull request #921: docs(book): turn underscores into dashes in page slugs
Author: login: ROMemories
Labels: name: docs
description: Improvements or additions to documentation
Created: 2025-03-19T15:12:51Z | Merged: 2025-03-27T15:10:52Z

# Description

<!-- Please write a summary of your changes and why you made them.-->
This renames book pages so that dashes are used instead of underscores, as dashes look friendlier.
A redirect is added for the "Getting started" page, as we've already advertized links to that page.

CI check links internal to the book, so that guarantees that these are not broken; it doesn't currently test the README or any source code yet however.

## How to review this PR

This PR is best reviewed commit by commit.

## Issues/PRs references

<!--
Examples: Fixes #1234. See also #5678. Depends on PR #9876.

Please use keywords (e.g., fixes, resolve) with the links to the issues you
resolved, this way they will be automatically closed when your pull request
is merged. See https://help.github.com/articles/closing-issues-using-keywords/.
-->

## Open Questions

<!-- Unresolved questions, if any. -->

## Change checklist

<!--
We don't enforce a strict convention for commit messages, but please make sure that
the commit history is clear and informative.
-->
- [x] I have cleaned up my commit history and squashed fixup commits.
- [x] I have followed the [Coding Conventions](https://ariel-os.github.io/ariel-os/dev/docs/book/coding-conventions.html).
- [x] I have performed a self-review of my own code.
- [x] I have made corresponding changes to the documentation.



Diff:
diff --git a/README.md b/README.md
index e01a449ca8..a95a0e9033 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,7 @@
 
 Ariel OS is an operating system for secure, memory-safe, low-power Internet of Things (IoT).
 It is based on Rust from the ground up
-and [supports hardware](https://ariel-os.github.io/ariel-os/dev/docs/book/hardware_functionality_support.html)
+and [supports hardware](https://ariel-os.github.io/ariel-os/dev/docs/book/hardware-functionality-support.html)
 based on 32-bit microcontroller architectures (Cortex-M, RISC-V, and Xtensa).
 
 ## Goals and Design
@@ -70,5 +70,5 @@ Thanks to all the people who already contributed!
 [rustdoc-badge]: https://img.shields.io/badge/Documentation-%F0%9F%93%94-blue
 [documentation-mdbook]: https://ariel-os.github.io/ariel-os/dev/docs/book/
 [documentation-dev-rustdoc]: https://ariel-os.github.io/ariel-os/dev/docs/api/
-[getting-started-mdbook]: https://ariel-os.github.io/ariel-os/dev/docs/book/getting_started.html
+[getting-started-mdbook]: https://ariel-os.github.io/ariel-os/dev/docs/book/getting-started.html
 [hello-world-example]: https://github.com/ariel-os/ariel-os/tree/main/examples/hello-world
diff --git a/book/book.toml b/book/book.toml
index 2d010a170d..d4c5c564ee 100644
--- a/book/book.toml
+++ b/book/book.toml
@@ -14,4 +14,12 @@ title = "Ariel OS manual"
 git-repository-url = "https://github.com/ariel-os/ariel-os"
 edit-url-template = "https://github.com/ariel-os/ariel-os/edit/main/book/{path}"
 
+[output.html.redirect]
+"/adding_board_support.html" = "adding-board-support.html"
+"/async_support.html" = "async-support.html"
+"/build_system.html" = "build-system.html"
+"/debug_console.html" = "debug-console.html"
+"/getting_started.html" = "getting-started.html"
+"/hardware_functionality_support.html" = "hardware-functionality-support.html"
+
 [preprocessor.cmdrun]
diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
index 3d64eb3a24..96aa7fa96d 100644
--- a/book/src/SUMMARY.md
+++ b/book/src/SUMMARY.md
@@ -1,15 +1,15 @@
 # Summary
 
 - [Introduction](./introduction.md)
-- [Hardware & Functionality Support](./hardware_functionality_support.md)
+- [Hardware & Functionality Support](./hardware-functionality-support.md)
 
 # User Guide
 
-- [Getting Started](./getting_started.md)
-- [Build System](./build_system.md)
+- [Getting Started](./getting-started.md)
+- [Build System](./build-system.md)
 - [Building an Application](./application.md)
-- [Async Executors](./async_support.md)
-- [Debug Console](./debug_console.md)
+- [Async Executors](./async-support.md)
+- [Debug Console](./debug-console.md)
 - [Networking](./networking.md)
 - [Randomness and Entropy](./randomness.md)
 - [Multithreading](./multithreading.md)
@@ -22,6 +22,6 @@
 
 # Developer Guide
 
-- [Adding Support for a Board](./adding_board_support.md)
+- [Adding Support for a Board](./adding-board-support.md)
 - [Coding Conventions](./coding-conventions.md)
 - [Code of Conduct](./CODE_OF_CONDUCT.md)
diff --git a/book/src/adding_board_support.md b/book/src/adding-board-support.md
similarity index 98%
rename from book/src/adding_board_support.md
rename to book/src/adding-board-support.md
index bf61831581..79e9491bc8 100644
--- a/book/src/adding_board_support.md
+++ b/book/src/adding-board-support.md
@@ -60,7 +60,7 @@ builders:
 
 MCU-specific items inside Ariel OS crates are gated behind
 `#[cfg(context = $CONTEXT)]` attributes, where `$CONTEXT` is the [MCU's `laze
-context` name](./build_system.md#laze-contexts).
+context` name](./build-system.md#laze-contexts).
 These need to be expanded for adding support for the new MCU.
 
 At least the following crates may need to be updated:
diff --git a/book/src/async_support.md b/book/src/async-support.md
similarity index 95%
rename from book/src/async_support.md
rename to book/src/async-support.md
index 9eeef8d71c..52cb60ed90 100644
--- a/book/src/async_support.md
+++ b/book/src/async-support.md
@@ -9,7 +9,7 @@ It comes in three different flavors, identified by their laze module names:
 
 | laze module              | Embassy executor | Description |
 | ------------------------ | ---------------- | ----------- |
-| `executor-interrupt`     | [InterruptExecutor][interrupt-executor-rustdoc] | Runs in handler mode. A software interrupt (SWI) handler is used when the MCU provides one, otherwise the [board configuration must specify](./adding_board_support.md#adding-support-for-a-board-1) which peripheral interrupt to dedicate to this executor. |
+| `executor-interrupt`     | [InterruptExecutor][interrupt-executor-rustdoc] | Runs in handler mode. A software interrupt (SWI) handler is used when the MCU provides one, otherwise the [board configuration must specify](./adding-board-support.md#adding-support-for-a-board-1) which peripheral interrupt to dedicate to this executor. |
 | `executor-single-thread` | [Executor][executor-rustdoc] | Runs in thread mode in place of threads. Therefore not compatible with [multithreading][multithreading-book]. |
 | `executor-thread`        | [Custom, based on `raw::Executor`][asynch-thread-executor-rustdoc] | Runs inside a dedicated thread automatically started at startup. |
 
@@ -35,7 +35,7 @@ Running multiple executors allows running them with different priorities.
 
 <!-- TODO: Power consumption optimization -->
 
-[laze-modules-book]: ./build_system.md#laze-modules
+[laze-modules-book]: ./build-system.md#laze-modules
 [multithreading-book]: ./multithreading.md
 [interrupt-executor-rustdoc]: https://docs.embassy.dev/embassy-executor/git/cortex-m/struct.InterruptExecutor.html
 [executor-rustdoc]: https://docs.embassy.dev/embassy-executor/git/cortex-m/struct.Executor.html
diff --git a/book/src/build_system.md b/book/src/build-system.md
similarity index 94%
rename from book/src/build_system.md
rename to book/src/build-system.md
index 85607c48ef..98afd3fa8b 100644
--- a/book/src/build_system.md
+++ b/book/src/build-system.md
@@ -22,7 +22,7 @@ For example, to run the hello-world example from the `ariel-os` directory, the c
 
 Tasks available in Ariel OS include:
 
-- `run`: Compiles, flashes, and runs an application. The [debug output](./debug_console.md) is printed in the terminal.
+- `run`: Compiles, flashes, and runs an application. The [debug output](./debug-console.md) is printed in the terminal.
 - `flash`: Compiles and flashes an application.
 - `debug`: Starts a GDB debug session for the selected application.
   The application needs to be flashed using the `flash` task beforehand.
@@ -48,7 +48,7 @@ To specify laze modules for an out-of-tree application, see [below](#enabling-la
 ## laze contexts
 
 The laze configuration defines a laze context for each MCU, MCU family, and board.
-These can be found in the [support matrix](./hardware_functionality_support.html), where they are called “Ariel OS name”.
+These can be found in the [support matrix](./hardware-functionality-support.html), where they are called “Ariel OS name”.
 
 Out-of-tree applications can be restricted to specific laze contexts, see [below](#restricting-an-application-to-specific-mcusboards).
 
@@ -57,13 +57,13 @@ This makes it possible to use the `#[cfg]` attribute to introduce feature-gates
 
 ## Out-of-tree applications
 
-New application projects should be [started from a template](./getting_started.md#starting-an-application-project-from-a-template-repository).
+New application projects should be [started from a template](./getting-started.md#starting-an-application-project-from-a-template-repository).
 Out-of-tree applications use the `laze-project.yml` file for configuration through laze.
 
 ### Importing Ariel OS
 
 Ariel OS's source and configuration are imported using [laze's `imports`][laze-imports-book] feature.
-The [project templates](./getting_started.md#starting-an-application-project-from-a-template-repository) use a [`git` import][laze-git-import-book] to ask laze to clone Ariel OS's repository.
+The [project templates](./getting-started.md#starting-an-application-project-from-a-template-repository) use a [`git` import][laze-git-import-book] to ask laze to clone Ariel OS's repository.
 The cloned repository is stored inside `build/imports`.
 
 > It is currently recommended to use Ariel OS's commit ID to track the repository, to avoid surprising changes.
diff --git a/book/src/debug_console.md b/book/src/debug-console.md
similarity index 98%
rename from book/src/debug_console.md
rename to book/src/debug-console.md
index bca90ab453..dd577dc8f3 100644
--- a/book/src/debug_console.md
+++ b/book/src/debug-console.md
@@ -66,6 +66,6 @@ Ariel OS's logger for `log` supports configuring the log level globally, but do
 [defmt]: https://github.com/knurling-rs/defmt
 [defmt documentation]: https://defmt.ferrous-systems.com/
 [log]: https://github.com/rust-lang/log
-[laze-modules-book]: ./build_system.md#laze-modules
+[laze-modules-book]: ./build-system.md#laze-modules
 [print-macro-rustdoc]: https://ariel-os.github.io/ariel-os/dev/docs/api/ariel_os/debug/macro.print.html
 [println-macro-rustdoc]: https://ariel-os.github.io/ariel-os/dev/docs/api/ariel_os/debug/macro.println.html
diff --git a/book/src/getting_started.md b/book/src/getting-started.md
similarity index 97%
rename from book/src/getting_started.md
rename to book/src/getting-started.md
index 41ac0c3502..5b59293cb6 100644
--- a/book/src/getting_started.md
+++ b/book/src/getting-started.md
@@ -62,7 +62,7 @@ It explains how to compile and run the `hello-word` example to verify your setup
 To check that everything is installed correctly, the `hello-word` example can be compiled and run from the `ariel-os` directory.
 The following assumes you have your target board connected to your host computer.
 
-Find the Ariel OS name of your supported board in the [support matrix](./hardware_functionality_support.html).
+Find the Ariel OS name of your supported board in the [support matrix](./hardware-functionality-support.html).
 
 > The following assumes the Nordic nRF52840-DK, whose Ariel OS name is `nrf52840dk`.
 > Replace that name with your board's.
@@ -124,7 +124,7 @@ laze build -b nrf52840dk run
 
 > The board name needs to be replaced with your board's.
 
-See the [Build System page](./build_system.md) to learn more about laze and how to work with out-of-tree applications.
+See the [Build System page](./build-system.md) to learn more about laze and how to work with out-of-tree applications.
 
 [ariel-os-repo]: https://github.com/ariel-os/ariel-os
 [ariel-os-hello-repo]: https://github.com/ariel-os/ariel-os-hello
diff --git a/book/src/hardware_functionality_support.md b/book/src/hardware-functionality-support.md
similarity index 100%
rename from book/src/hardware_functionality_support.md
rename to book/src/hardware-functionality-support.md
diff --git a/book/src/introduction.md b/book/src/introduction.md
index 0551218f2e..cbcd703b41 100644
--- a/book/src/introduction.md
+++ b/book/src/introduction.md
@@ -3,7 +3,7 @@
 Ariel OS is an operating system for secure, memory-safe, networked applications
 running on low-power microcontrollers.
 It is based on Rust from the ground up
-and [supports hardware](https://ariel-os.github.io/ariel-os/dev/docs/book/hardware_functionality_support.html)
+and [supports hardware](https://ariel-os.github.io/ariel-os/dev/docs/book/hardware-functionality-support.html)
 based on 32-bit microcontroller architectures (Cortex-M, RISC-V, and Xtensa).
 Many features provided by Ariel OS can individually be enabled or disabled at build time
 in order to minimize resource consumption.
diff --git a/book/src/multithreading.md b/book/src/multithreading.md
index cdf6140be2..9427a53f45 100644
--- a/book/src/multithreading.md
+++ b/book/src/multithreading.md
@@ -56,4 +56,4 @@ It allows to restrict the execution of a thread to a specific core and prevent i
 [max-thread-count-rustdoc]: https://ariel-os.github.io/ariel-os/dev/docs/api/ariel_os/thread/constant.THREAD_COUNT.html
 [set-priority-rustdoc]: https://ariel-os.github.io/ariel-os/dev/docs/api/ariel_os/thread/fn.set_priority.html
 [sched-prio-levels-rustdoc]: https://ariel-os.github.io/ariel-os/dev/docs/api/ariel_os/thread/constant.SCHED_PRIO_LEVELS.html
-[laze-modules-book]: ./build_system.md#laze-modules
+[laze-modules-book]: ./build-system.md#laze-modules
diff --git a/book/src/networking.md b/book/src/networking.md
index d44936600f..ade3e460e0 100644
--- a/book/src/networking.md
+++ b/book/src/networking.md
@@ -31,9 +31,9 @@ CONFIG_WIFI_NETWORK=<ssid> CONFIG_WIFI_PASSWORD=<pwd> laze build ...
 ### Network Configuration
 
 DHCPv4 is used by default for network configuration, including for IP address allocation.
-This is enabled by the `network-config-dhcp` [laze module](./build_system.md#laze-modules), selected by default.
+This is enabled by the `network-config-dhcp` [laze module](./build-system.md#laze-modules), selected by default.
 
-In order to provide a static configuration, select the `network-config-static` [laze module](./build_system.md#laze-modules), which will take precedence.
+In order to provide a static configuration, select the `network-config-static` [laze module](./build-system.md#laze-modules), which will take precedence.
 The configuration can be customized with the following environment variables:
 
 | Variable                                 | Default      |
@@ -87,4 +87,4 @@ a second cable.
 [network-stack-rustdoc]: https://ariel-os.github.io/ariel-os/dev/docs/api/ariel_os/net/fn.network_stack.html
 [embassy-net-reexport-rustdoc]: https://ariel-os.github.io/ariel-os/dev/docs/api/ariel_os/reexports/embassy_net/index.html
 [examples-dir-repo]: https://github.com/ariel-os/ariel-os/tree/main/examples
-[laze-modules-book]: ./build_system.md#laze-modules
+[laze-modules-book]: ./build-system.md#laze-modules
diff --git a/book/src/randomness.md b/book/src/randomness.md
index 8931e64adf..53ffee96b9 100644
--- a/book/src/randomness.md
+++ b/book/src/randomness.md
@@ -20,4 +20,4 @@ When the `random` module is selected, the `hwrng` [laze module][laze-modules-boo
 
 [fast-rng-fn-rustdoc]: https://ariel-os.github.io/ariel-os/dev/docs/api/ariel_os/random/fn.fast_rng.html
 [crypto-rng-fn-rustdoc]: https://ariel-os.github.io/ariel-os/dev/docs/api/ariel_os/random/fn.crypto_rng.html
-[laze-modules-book]: ./build_system.md#laze-modules
+[laze-modules-book]: ./build-system.md#laze-modules
diff --git a/book/src/storage.md b/book/src/storage.md
index d5e1ee5de4..9489e11ab5 100644
--- a/book/src/storage.md
+++ b/book/src/storage.md
@@ -66,7 +66,7 @@ especially at startup when there is the danger of endless writing
 due to a crash leading to a reboot.
 
 [sequential-storage]: https://crates.io/crates/sequential-storage
-[laze-modules-book]: ./build_system.md#laze-modules
+[laze-modules-book]: ./build-system.md#laze-modules
 [storage-example-repo]: https://github.com/ariel-os/ariel-os/tree/main/examples/storage
 [storage module]: https://ariel-os.github.io/ariel-os/dev/docs/api/ariel_os/storage/index.html
 [serde-serialize]: https://docs.rs/serde/latest/serde/trait.Serialize.html
diff --git a/book/src/testing.md b/book/src/testing.md
index e2a720ad7c..6b82f9708f 100644
--- a/book/src/testing.md
+++ b/book/src/testing.md
@@ -66,7 +66,7 @@ name = "test"
 harness = false
 ```
 
-3. Enable the `embedded-test` or `embedded-test-only` [laze module](./build_system.md#laze-modules):
+3. Enable the `embedded-test` or `embedded-test-only` [laze module](./build-system.md#laze-modules):
 
 ```yaml
 apps:
diff --git a/book/src/tooling/coap.md b/book/src/tooling/coap.md
index c948dda508..4449db1a38 100644
--- a/book/src/tooling/coap.md
+++ b/book/src/tooling/coap.md
@@ -287,4 +287,4 @@ without the need for the CoAP client to create a network connection to the host.
 
 [New ACE Workflow developed in ACE]: https://www.ietf.org/archive/id/draft-ietf-ace-workflow-and-params-00.html#name-new-ace-workflow
 
-[laze-modules-book]: ../build_system.md#laze-modules
+[laze-modules-book]: ../build-system.md#laze-modules
diff --git a/src/ariel-os-hal/src/lib.rs b/src/ariel-os-hal/src/lib.rs
index 17b0c3e7c8..56fde92819 100644
--- a/src/ariel-os-hal/src/lib.rs
+++ b/src/ariel-os-hal/src/lib.rs
@@ -10,7 +10,7 @@
 //! | STMicroelectronics   | STM32       | STM32WB55RGVX     | [`ariel-os-stm32::*`](../../ariel_os_stm32/index.html) |
 //!
 //! Documentation is only rendered for the MCUs listed in the table above, but [many others are
-//! supported](https://ariel-os.github.io/ariel-os/dev/docs/book/hardware_functionality_support.html).
+//! supported](https://ariel-os.github.io/ariel-os/dev/docs/book/hardware-functionality-support.html).
 //! To render the docs locally for the MCU of your choice, adapt [the `cargo doc` command used to
 //! generate documentation for the relevant
 //! crate](https://github.com/ariel-os/ariel-os/blob/main/.github/workflows/build-deploy-docs.yml).


Reviews:
user: login: chrysn
state: CHANGES_REQUESTED
author_association: MEMBER
submitted_at: 2025-03-21T21:49:34Z
user: login: kaspar030
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-27T12:54:33Z
user: login: kaspar030
body: LGTM.
state: APPROVED
author_association: MEMBER
submitted_at: 2025-03-27T12:55:02Z
user: login: chrysn
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-27T13:59:57Z
user: login: chrysn
state: APPROVED
author_association: MEMBER
submitted_at: 2025-03-27T14:25:35Z

Review comments:
diff_hunk: @@ -14,4 +14,7 @@ title = "Ariel OS manual"
 git-repository-url = "https://github.com/ariel-os/ariel-os"
 edit-url-template = "https://github.com/ariel-os/ariel-os/edit/main/book/{path}"
 
+[output.html.redirect]
+"/getting_started.html" = "getting-started.html"
path: book/book.toml
user: login: chrysn
body: This should cover all changed names: We advertised all of them by putting them out, and there is no way of knowing to which people put links of which they bookmarked.
created_at: 2025-03-21T21:49:26Z
author_association: MEMBER
diff_hunk: @@ -14,4 +14,7 @@ title = "Ariel OS manual"
 git-repository-url = "https://github.com/ariel-os/ariel-os"
 edit-url-template = "https://github.com/ariel-os/ariel-os/edit/main/book/{path}"
 
+[output.html.redirect]
+"/getting_started.html" = "getting-started.html"
path: book/book.toml
user: login: kaspar030
body: Let's change this now and run with it, no need to list those links forever.
created_at: 2025-03-27T12:54:33Z
author_association: MEMBER
diff_hunk: @@ -14,4 +14,7 @@ title = "Ariel OS manual"
 git-repository-url = "https://github.com/ariel-os/ariel-os"
 edit-url-template = "https://github.com/ariel-os/ariel-os/edit/main/book/{path}"
 
+[output.html.redirect]
+"/getting_started.html" = "getting-started.html"
path: book/book.toml
user: login: chrysn
body: ```suggestion
"/adding_board_support.html" = "adding-board-support.html"
"/async_support.html" = "async-support.html"
"/build_system.html" = "build-system.html"
"/debug_console.html" = "debug-console.html"
"/getting_started.html" = "getting-started.html"
"/hardware_functionality_support.html" = "hardware-functionality-support.html"
```

This should be the complete list thanks to git diff --stat and some vim magic.
created_at: 2025-03-27T13:59:56Z
author_association: MEMBER

PR comments:
user: login: github-actions[bot]
created_at: 2025-03-19T15:15:12Z
body: 🚀 Documentation preview deployed to <https://ariel-os-docs-preview-pr921.surge.sh/dev/docs/api/ariel_os/>
📔 Book preview deployed to <https://ariel-os-docs-preview-pr921.surge.sh/dev/docs/book/>
<!-- Sticky Pull Request Comment -->
author_association: NONE
user: login: kaspar030
created_at: 2025-03-27T12:55:42Z
body: @chrysn your call, if you think it is that important, we can also list the filenames there!
author_association: MEMBER
user: login: chrysn
created_at: 2025-03-27T14:26:21Z
body: Thanks, please squash and merge.
author_association: MEMBER