Merge pull request #21728 from LasseRosenow/guides-refactor-titles

Teufelchen1 · web-flow · commit 31a05b5d6c57 · 2025-09-19T09:17:40.000Z
doc/guides: cleanup section titles
diff --git a/doc/guides/advanced_tutorials/creating_application.md b/doc/guides/advanced_tutorials/creating_application.md
@@ -1,6 +1,6 @@
 ---
-title: Creating an application
-description: How to create your own application for RIOT-OS
+title: Creating an Application
+description: How to create your own application for RIOT
 ---
 
 To create your own application you need to create a directory containing one or
@@ -58,7 +58,7 @@ RIOTBASE ?= $(CURDIR)/../../RIOT
 include $(RIOTBASE)/Makefile.include
 ```
 
-### How to handle unsupported boards?
+### How to handle Unsupported Boards?
 
 Sometimes it is necessary to exclude boards because they don't provide a
 required functionality or don't have sufficient memory. RIOT's build system
@@ -143,7 +143,7 @@ on the module implementation.
 For applications, the `Makefile` is generated with the dependencies (modules,
 packages, required features) included.
 
-## Usage:
+## Usage
 
 To generate an example application, e.g in the `examples` directory, from the
 RIOT base directory, run:
diff --git a/doc/guides/advanced_tutorials/creating_modules.md b/doc/guides/advanced_tutorials/creating_modules.md
@@ -1,5 +1,5 @@
 ---
-title: Creating modules
+title: Creating Modules
 description: Guide on how to create modules in RIOT-OS
 ---
 
diff --git a/doc/guides/advanced_tutorials/device_drivers.md b/doc/guides/advanced_tutorials/device_drivers.md
@@ -63,7 +63,7 @@ This should be clearly stated in the device driver's documentation so that
 anyone wanting to use the driver can find out the supported features without
 having to scan through the code.
 
-## Device descriptor and parameter configuration
+## Device Descriptor and Parameter Configuration
 
 Each device MUST supply a data structure, holding the devices state and
 configuration, using the naming scheme of `DEVNAME_t` (e.g. `dht_t`, or
@@ -108,7 +108,7 @@ configuration data that is only used once can be read directly from ROM, while
 often used fields (e.g. used peripherals) are stored directly in the device
 descriptor and one saves hereby one de-referencing step when accessing them.
 
-## Default device configuration
+## Default Device Configuration
 
 Each device driver in RIOT MUST supply a default configuration file, named
 `DEVNAME_params.h`. This file should be located in the `RIOT/drivers/...`. The
@@ -201,7 +201,7 @@ Third, we can define more than a single device in the board configuration
 And finally, we can simply override the `tmpabc_params.h` file as described
 above.
 
-## Compile-time configuration documentation
+## Compile-time Configuration Documentation
 
 The macros that configure the driver during compilation is added to the listing
 for [Compile time configurations](https://doc.riot-os.org/group__config.html). Refer to the following example
@@ -322,9 +322,9 @@ one of them - whatever makes most sense for a given function.
 - *MUST*: use `const devab_t *dev` when the device descriptor can be access
   read-only
 
-## Build system integration
+## Build System Integration
 
-### Internal include files
+### Internal Include Files
 
 If the driver contains internal include files, a `Makefile.include` must be
 added in the driver implementation directory, with the following content
@@ -335,7 +335,7 @@ USEMODULE_INCLUDES_<driver name> := $(LAST_MAKEFILEDIR)/include
 USEMODULE_INCLUDES += $(USEMODULE_INCLUDES_<driver name>)
 ```
 
-### External dependencies
+### External Dependencies
 
 If the driver has other module or CPU features dependencies (like `xtimer` or
 `periph_i2c`), they must be added in the `$(RIOTBASE)/drivers/Makefile.dep`
@@ -351,7 +351,7 @@ endif
 
 **Warning:** Please be careful with alphabetical order when modifying this file.
 
-## Helper tools
+## Helper Tools
 
 To help you start writing a device driver, the RIOT build system provides the
 `generate-driver` make target. It is a wrapper around the
@@ -422,9 +422,9 @@ int tmpabc_init(tmpabc_t *dev, const tmpabc_params_t *params);
 
 After this function is called, the device MUST be running and usable.
 
-## Value handling
+## Value Handling
 
-### Value semantics
+### Value Semantics
 
 All sensors in RIOT MUST return their reading results as real physical values.
 When working with sensor data, these are the values of interest, and the
@@ -459,7 +459,7 @@ just return centi-degree instead of degree (e.g. 2372c°C instead of 23.72°C).
 - *SHOULD*: the driver exports functions for putting it to sleep and waking up
   the device
 
-# Network devices
+# Network Devices
 
 ## Initialization
 
diff --git a/doc/guides/advanced_tutorials/porting_boards.md b/doc/guides/advanced_tutorials/porting_boards.md
@@ -282,7 +282,7 @@ when starting to port a board: all required files are generated with
 copyright headers, doxygen groups, etc, so you can concentrate on the port.
 The board source files are created in the `boards/<board name>` directory.
 
-## Usage:
+## Usage
 
 From the RIOT base directory, run:
 
diff --git a/doc/guides/build-system/advanced_build_system_tricks.md b/doc/guides/build-system/advanced_build_system_tricks.md
@@ -7,7 +7,7 @@ This page describes some build systems tricks that can help developers but are n
 
 They are low level commands that should not be taken as part of a stable API but better have a documentation than only having a description in the build system code.
 
-## Customize the build system
+## Customize the Build System
 
 - `RIOT_MAKEFILES_GLOBAL_PRE`: files parsed before the body of `$RIOTBASE/Makefile.include`
 - `RIOT_MAKEFILES_GLOBAL_POST`: files parsed after the body of `$RIOTBASE/Makefile.include`
@@ -23,7 +23,7 @@ You can configure your own files that will be parsed by the build system main `M
 - Define your custom targets
 - Override default targets
 
-## Speed-up builds with ccache
+## Speed-up Builds with ccache
 
 [`ccache`](https://ccache.samba.org/) is a compiler cache. It speeds up recompilation by caching previous compilations and detecting when the same compilation is being done again.
 
@@ -101,7 +101,7 @@ sys     0m0.327s
 [kaspar@booze default (master)]$
 ```
 
-## Analyze dependency resolution
+## Analyze Dependency Resolution
 
 When refactoring dependency handling or modifying variables used for dependency resolution, one may want to evaluate the impact on the existing applications. This describe some debug targets to dump variables used during dependency resolution.
 
@@ -123,7 +123,7 @@ For more configuration and usage details, see in the file defining the targets `
 
 To do a repository wide analysis, you can use the script `dist/tools/buildsystem_sanity_check/save_all_dependencies_resolution_variables.sh` that will generate the output for all boards and applications. It currently take around 2 hours on an 8 cores machine with ssd.
 
-## Generate Makefile.ci content
+## Generate Makefile.ci Content
 
 Most applications and tests include a `Makefile.ci` to indicate which boards cannot compile the application or test. The content for these files can be generated via the script in:
 
diff --git a/doc/guides/build-system/build_system_basics.md b/doc/guides/build-system/build_system_basics.md
@@ -70,7 +70,7 @@ For a `FEATURE` to be provided by a `board` it must meet 2 criteria, and for
 
 ### Where to define FEATURES\_%
 
-- `FEATURES_PROVIDED`, `FEATURES_CONFLICT` and `FEATURES_CONFLICT_MSG ` are
+- `FEATURES_PROVIDED`, `FEATURES_CONFLICT` and `FEATURES_CONFLICT_MSG` are
   defined in `Makefile.features`
 
 - `FEATURES_REQUIRED`, `FEATURES_OPTIONAL`, `FEATURES_REQUIRED_ANY`,
@@ -134,7 +134,7 @@ summarizes some of the pros and cons as well as specifies good and bad patterns
 in our build system. You might want to refer to `gnu make` documentation
 regarding these subjects.
 
-## Avoid unnecessary export
+## Avoid Unnecessary Export
 
 ```
 export OUTPUT = $(shell some-command)
@@ -154,9 +154,9 @@ This is why global variables need clear documentation.
 
 [gnumake doc](https://www.gnu.org/software/make/manual/html_node/Variables_002fRecursion.html)
 
-## Use memoized for variables referencing a function or command
+## Use Memoized for Variables Referencing a Function or Command
 
-### recursively expanded variable:
+### Recursively Expanded Variable
 
 ```
 OUTPUT = $(shell some-command $(ANOTHER_VARIABLE))
@@ -175,7 +175,7 @@ OUTPUT = $(shell some-command $(ANOTHER_VARIABLE))
 - If the variable expansion doesn't involve evaluating a function the overhead
   is none.
 
-### simply expanded variable:
+### Simply Expanded Variable
 
 ```
 OUTPUT := $(shell some-command $(ANOTHER_VARIABLE))
@@ -193,7 +193,7 @@ OUTPUT := $(shell some-command $(ANOTHER_VARIABLE))
 
 - The values of variables declared with `:=` depend on the order of definition.
 
-### memoized:
+### Memoized
 
 ```
 OUTPUT = $(call memoized,OUTPUT,$(shell some-command))
@@ -208,7 +208,7 @@ OUTPUT = $(call memoized,OUTPUT,$(shell some-command))
 
 [gnumake doc](https://www.gnu.org/software/make/manual/html_node/Flavors.html)
 
-## Additional documentation
+## Additional Documentation
 
 - Deferred vs. simple expansion: http://make.mad-scientist.net/deferred-simple-variable-expansion/
 - Tracking issue: [#10850](https://github.com/RIOT-OS/RIOT/issues/10850)
diff --git a/doc/guides/build-system/flashing.md b/doc/guides/build-system/flashing.md
@@ -356,7 +356,7 @@ So the current filename should be higher than 60-serial.rules
 If for some reason re-writing the serial is needed there is a windows tool:
   https://remoteqth.com/wiki/index.php?page=How+to+set+usb+device+SerialNumber
 
-## Documentation:
+## Documentation
 * The whole documentation
   http://reactivated.net/writing_udev_rules.html#udevinfo
 * Udev manpage
diff --git a/doc/guides/c_tutorials/create_project.mdx b/doc/guides/c_tutorials/create_project.mdx
@@ -18,7 +18,7 @@ you can skip to the next section.
 
 <GitSetup />
 
-## Step 2: Creating our hello world program
+## Step 2: Creating our Hello World Program
 
 Now that we have added RIOT as a submodule to our project,
 we can start writing our hello world program.
@@ -98,7 +98,7 @@ include $(RIOTBASE)/Makefile.include
 Congratulations! You have now created a new project with a simple hello world program.
 In the next step, we will build and run our program just like we did in the "Getting Started" guide.
 
-## Step 4: Building and running the program
+## Step 4: Building and Running the Program
 
 <Contact />
 
diff --git a/doc/guides/c_tutorials/gpio.mdx b/doc/guides/c_tutorials/gpio.mdx
@@ -262,7 +262,7 @@ Be careful to not press the reset button by mistake 😉
   Your browser does not support the video tag.
 </video>
 
-## Extra: Board specific defines
+## Extra: Board Specific Defines
 
 Most boards (if they have LEDs or buttons) will have
 specific defines for the GPIO pins that are used.
diff --git a/doc/guides/getting-started/finding_modules.mdx b/doc/guides/getting-started/finding_modules.mdx
@@ -12,7 +12,7 @@ In the previous tutorial, we created a simple hello world program and you might
 
 Lets take a look at how we can use modules in RIOT and where to find them.
 
-## Step 1: Finding modules
+## Step 1: Finding Modules
 
 RIOT provides a number of modules that you can use in your application, including modules for networking, sensors, and more.
 Depending on the goal of your application, you might need to use different modules and sometimes even create your own. So where can you find these modules?
@@ -47,7 +47,7 @@ Let's say I want to use base64 encoding in my application. I can search the RIOT
 
 <Contact/>
 
-## Step 2: Using modules
+## Step 2: Using Modules
 
 Using modules in RIOT is quite simple. You just need to list any modules that you want to use in your application in the `Makefile` of your application.
 
diff --git a/doc/guides/getting-started/install-wsl.mdx b/doc/guides/getting-started/install-wsl.mdx
@@ -227,7 +227,7 @@ Eventually, the setup will inform you of the completion of the installation.
 
 1. Click the "Close" button to acknowledge.
 
-## Attach a USB device to WSL
+## Attach a USB Device to WSL
 
 :::note
 Attaching a USB device to WSL needs to be repeated after any of the following
diff --git a/doc/guides/getting-started/installing.mdx b/doc/guides/getting-started/installing.mdx
@@ -37,7 +37,7 @@ What works well is using Linux in a virtual machine, but at much lower performan
 
 We also offer Docker images that make it a bit easier to develop on macOS.
 
-## Installing the required software packages
+## Installing the Required Software Packages
 
 :::note
 It is also possible to run RIOT in a Docker container.
diff --git a/doc/guides/misc/dev_best_practices.md b/doc/guides/misc/dev_best_practices.md
@@ -90,7 +90,7 @@ int bar(foo_t v) {
    Use internal functions to this end.
  * Don't mix up logical and bitwise operations (`!` vs `~`, or `&&` vs `&`)
 
-## Methodology: emulator first, target IoT hardware last!
+## Methodology: Emulator first, Target IoT Hardware last!
 
 The below methodology is recommended, using well-known de facto standard tools from the FLOSS community that are
 compatible with RIOT. Using the below workflow improves time-to-running-code compared to typical IoT software
@@ -133,13 +133,13 @@ Both ways have some drawbacks which are listed here.
 If you want to analyze the static memory consumption of your code you can use
 [otm](https://github.com/LudwigOrtmann/otm) or `make cosy`.
 
-### Static memory
+### Static Memory
 * Access the memory in one operation O(1) ⇒ real time condition
 * Programmer needs to know the amount of memory on compile time
   * Leads to over and undersized buffers
 * Forces the programmer to think about the amount of need memory at compile time
 
-### Dynamic memory
+### Dynamic Memory
 * `malloc()` and `free()` are implemented in your `libc` (RIOT on ARM: `newlib`/`picolib`)
   * Runtime behavior is not predictable
 * Code can request the amount of memory it needs on runtime
diff --git a/doc/guides/misc/emulators.md b/doc/guides/misc/emulators.md
@@ -79,7 +79,7 @@ Qemu is usually available via the package manager of common Linux distributions.
 Depending on your local system, the installation procedure is described on the
 [qemu website](https://www.qemu.org/download/).
 
-## Boards supported
+## Supported Boards
 
 So far, in RIOT, only the
 [BBC micro:bit](https://doc.riot-os.org/group__boards__microbit.html)
@@ -105,7 +105,7 @@ hardware - but with more possibilities.
 
 ## Installation
 
-### From package
+### From Package
 
 Packages for macOS, deb-based and rpm-based systems, for Windows and for Arch
 Linux are available on [GitHub](https://github.com/renode/renode/releases/latest).
diff --git a/doc/guides/misc/how_to_doc.md b/doc/guides/misc/how_to_doc.md
@@ -13,7 +13,7 @@ For RIOT Starlight is meant to exclusively host guides while the API documentati
 Where Doxygen has a very automated approach to generating documentation, Starlight is meant to be more flexible and allow for a more human touch that is needed for tutorials and guides,
 which means that we both have the control over the content and layout but at the same time have to put more active effort into the UX of the documentation itself. At the same time writing guides in Markdown allows us to keep the guides readable in the repository itself, which is a big plus.
 
-## How to run the site locally
+## How to run the Site locally
 
 To run the site locally, you need to have [Node.js](https://nodejs.org/) installed.
 It is highly recommended to use a version manager such as [NVM](https://github.com/nvm-sh/nvm) to manage your Node.js versions.
@@ -70,7 +70,7 @@ Generally, there are two folders that are important for the guides:
 
 We will go into more detail about how to create a new guide in the next section, but for now, it is important to understand that the guides are located in the `doc/guides/` folder and the configuration files are located in the `doc/starlight/` folder.
 
-## How to create a new guide
+## How to Create a new Guide
 
 Now that we understand how to run the site locally, let's look at how to create a new guide.
 The first step is to create a Markdown file within `doc/guides/` with the following structure:
@@ -106,7 +106,7 @@ Please always keep in mind that the more non-standard Markdown you write, the mo
 If you are targeting an experienced audience, a lot of them will be reading the guides locally within their IDE and not in a browser.
 :::
 
-### Placing the guide
+### Placing the Guide
 
 One last manual step is to add the new guide to the navigation. This is done in the `doc/starlight/astro.config.mjs` file.
 
@@ -122,7 +122,7 @@ You can either add your guide to an existing section or create a new section. In
 There is one exception to this rule, if your file is called index.md, the slug will be the name of the folder it is in. For example `doc/guides/test/index.md` will have the slug `test`.
 :::
 
-### Creating a new section
+### Creating a new Section
 
 Generally, we want to avoid creating new sections unless absolutely necessary. For example, if you create a totally new tutorial that spans multiple files, it might make sense to create a new section.
 In this case, you can create a new section by adding a new entry to the `sidebar` array in the `astro.config.mjs` file. The entry should look like this:
diff --git a/doc/guides/misc/terminal_config.md b/doc/guides/misc/terminal_config.md
diff --git a/doc/guides/rust_tutorials/create_project.mdx b/doc/guides/rust_tutorials/create_project.mdx
diff --git a/doc/guides/rust_tutorials/rust_in_riot.md b/doc/guides/rust_tutorials/rust_in_riot.md
diff --git a/doc/starlight/src/components/gitsetup.mdx b/doc/starlight/src/components/gitsetup.mdx
