Documentation: Fix header levels

This fixes the following MyST Parser warnings:

- Non-consecutive header level increase
- Document headings start at H2, not H1

The header levels (the number of "#" characters before a heading) are
intended to form a logical hierarchy of each section and subsection in a
document. A subsection typically should have a header level one more
than its parent section. Most of these warnings are caused by extra "#"
characters, which were simply removed, or sections missing a "#"
character to make it fall under its parent section.

Notable changes:

getting_started/kconfig.md: Changed the header level of the "Keywords"
section from 2 to 3 to fall under "Kconfig Language" (level 2), and
increased the level of each keyword from 3 to 4 to remain under
"Keywords". This also fixes the warnings of "H3 to H5" increases, since
the Usage/Example/Notes/Restrictions sections for each keyword had a
level of 5.

soc/intel/cse_fw_update/cse_fw_update.md: Changed the first line to a
top level header acting as the title of the document. Without this
soc/intel/index.md displays all the level 2 headers in this document
instead of a single link to cse_fw_update.md.

Change-Id: Ia1f8b52e39b7b6524bef89a95365541235b5b1b9
Signed-off-by: Nicholas Chin <nic.c3.14@gmail.com>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/83382
Reviewed-by: Felix Singer <service+coreboot-gerrit@felixsinger.de>
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Elyes Haouas <ehaouas@noos.fr>

11 files changed, 65 insertions, 66 deletions

diff --git a/Documentation/getting_started/kconfig.md b/Documentation/getting_started/kconfig.md
index c9e9b3c61a..bff077c47f 100644
--- a/Documentation/getting_started/kconfig.md
+++ b/Documentation/getting_started/kconfig.md
@@ -200,9 +200,9 @@ values to be set based on other values.
   visible in the front end.
 
 
-## Keywords
+### Keywords
 
-### bool
+#### bool
 
 The 'bool' keyword assigns a boolean type to a symbol. The allowable values for
 a boolean type are 'n' or 'y'. The keyword can be followed by an optional prompt
@@ -238,7 +238,7 @@ bool \[prompt\] \[if <expr>\]
 
 --------------------------------------------------------------------------------
 
-### choice
+#### choice
 
 This creates a selection list of one or more boolean symbols. For bools, only
 one of the symbols can be selected, and one will be be forced to be selected,
@@ -301,7 +301,7 @@ choice \[symbol\]
 
 --------------------------------------------------------------------------------
 
-### comment
+#### comment
 
 This keyword defines a line of text that is displayed to the user in the
 configuration frontend and is additionally written to the output files.
@@ -326,7 +326,7 @@ comment <prompt>
 
 --------------------------------------------------------------------------------
 
-### config
+#### config
 
 This is the keyword that starts a block defining a Kconfig symbol. The symbol
 modifiers follow the 'config' statement.
@@ -363,7 +363,7 @@ config <symbol>
 
 --------------------------------------------------------------------------------
 
-### default
+#### default
 
 The ‘default’ keyword assigns a value to a symbol in the case where no preset
 value exists, i.e. the symbol is not present and assigned in .config.  If there
@@ -403,7 +403,7 @@ default <expr> \[if <expr>\]
 
 --------------------------------------------------------------------------------
 
-### def_bool
+#### def_bool
 
 ‘def_bool’ is similar to the 'bool' keyword in that it sets a symbol’s type to
 boolean. It lets you set the type and default value at the same time, instead
@@ -437,7 +437,7 @@ def_bool <expr> \[if <expr>\]
 
 --------------------------------------------------------------------------------
 
-### depends on
+#### depends on
 
 This defines a dependency for a menu entry, including symbols and comments.  It
 behaves the same as surrounding the menu entry with an if/endif block.  If the
@@ -466,28 +466,28 @@ depends on <expr>
 
 --------------------------------------------------------------------------------
 
-### endchoice
+#### endchoice
 
 This ends a choice block. See the 'choice' keyword for more information and an
 example.
 
 --------------------------------------------------------------------------------
 
-### endif
+#### endif
 
 This ends a block started by the 'if' keyword. See the 'if' keyword for more
 information and an example.
 
 --------------------------------------------------------------------------------
 
-### endmenu
+#### endmenu
 
 This ends a menu block. See the 'menu' keyword for more information and an
 example.
 
 --------------------------------------------------------------------------------
 
-### help
+#### help
 
 The 'help' keyword defines the subsequent block of text as help for a config or
 choice block. The help block is started by the 'help' keyword on a line by
@@ -519,7 +519,7 @@ help <help text>
 
 --------------------------------------------------------------------------------
 
-### hex
+#### hex
 
 This is another symbol type specifier, specifying an unsigned integer value
 formatted as hexadecimal.
@@ -555,7 +555,7 @@ hex <expr> \[if <expr>\]
 
 --------------------------------------------------------------------------------
 
-### if
+#### if
 
 The 'if' keyword is overloaded, used in two different ways. The first definition
 enables and disables various other keywords, and follows the other keyword
@@ -596,7 +596,7 @@ endif
 
 --------------------------------------------------------------------------------
 
-### int
+#### int
 
 A type setting keyword, defines a symbol as an integer, accepting only signed
 numeric values.  The values can be further restricted with the ‘range’ keyword.
@@ -632,7 +632,7 @@ int <expr> \[if <expr>\]
 
 --------------------------------------------------------------------------------
 
-### mainmenu
+#### mainmenu
 
 The 'mainmenu' keyword sets the title or title bar of the configuration front
   end, depending on how the configuration program decides to use it. It can only
@@ -652,7 +652,7 @@ mainmenu "coreboot configuration"
 
 --------------------------------------------------------------------------------
 
-### menu
+#### menu
 
 The 'menu' and 'endmenu' keywords tell the configuration front end that the
 enclosed statements are part of a group of related pieces.
@@ -699,7 +699,7 @@ endmenu
 
 --------------------------------------------------------------------------------
 
-### prompt
+#### prompt
 
 The 'prompt' keyword sets the text displayed for a config symbol or choice in
 configuration front end.
@@ -752,7 +752,7 @@ prompt <prompt> \[if <expr>\]
             prompt "Prompt value 2"
 --------------------------------------------------------------------------------
 
-### range
+#### range
 
 This sets the allowable minimum and maximum entries for hex or int type config
 symbols.
@@ -774,7 +774,7 @@ range <symbol> <symbol> \[if <expr>\]
 
 --------------------------------------------------------------------------------
 
-### select
+#### select
 
 The ‘select’ keyword is used within a bool type config block.  In coreboot (and
 other projects that don't use modules), the 'select' keyword can force an
@@ -818,7 +818,7 @@ select <symbol> \[if <expr>\]
 
 --------------------------------------------------------------------------------
 
-### source
+#### source
 
 The 'source' keyword functions much the same as an 'include' statement in c.
 This pulls one or more files into Kconfig at the location of the 'source'
@@ -877,7 +877,7 @@ statements that generate a list of all the platform names:
 
 --------------------------------------------------------------------------------
 
-### string
+#### string
 
 The last of the symbol type assignment keywords. 'string' allows a text value to
 be entered.
@@ -923,7 +923,7 @@ keyword later. See the prompt keyword for more notes.
 
 
 
-## Keywords not used in coreboot at the time of writing:
+### Keywords not used in coreboot at the time of writing:
 
 - allnoconfig_y:
 - defconfig_list
@@ -948,7 +948,7 @@ statements:
     #define SYMBOL NAME XXX
 
 
-##### Symbol types:
+#### Symbol types:
 - bool, int, and hex types -  Every symbol of one of these types created in the
   Kconfig tree is defined.  It doesn’t matter whether they’re in an if/endif
   block, or have a ‘depends on’ statement - they ALL end up being defined in
@@ -1168,19 +1168,19 @@ saved .config file. As always, a 'select' statement overrides any specified
 
 ## Kconfig Editor Highlighting
 
-#### vim:
+### vim:
 
 vim has syntax highlighting for Kconfig built in (or at least as a part of
 vim-common), but most editors do not.
 
 
-#### ultraedit:
+### ultraedit:
 
 https://github.com/martinlroth/wordfiles/blob/master/kconfig.uew
 
 
 
-#### atom:
+### atom:
 
 https://github.com/martinlroth/language-kconfig
 
diff --git a/Documentation/mainboard/lenovo/montevina_series.md b/Documentation/mainboard/lenovo/montevina_series.md
index e4e5da3c5f..120a161e90 100644
--- a/Documentation/mainboard/lenovo/montevina_series.md
+++ b/Documentation/mainboard/lenovo/montevina_series.md
@@ -46,7 +46,7 @@ Now you need to patch the flash descriptor. You can either [modify the one from
 your backup with **ifdtool**](#modifying-flash-descriptor-using-ifdtool), or
 [use one from the coreboot repository](#using-checked-in-flash-descriptor-via-bincfg).
 
-#### Modifying flash descriptor using ifdtool
+### Modifying flash descriptor using ifdtool
 
 Pick the layout according to your chip size from the table below and save it to
 the `new_layout.txt` file:
@@ -88,7 +88,7 @@ $ mv flashregion_0_flashdescriptor.bin.new.new flashregion_0_flashdescriptor.bin
 
 Continue to the [Configuring coreboot](#configuring-coreboot) section.
 
-#### Using checked-in flash descriptor via bincfg
+### Using checked-in flash descriptor via bincfg
 
 There is a copy of an X200's flash descriptor checked into the coreboot
 repository. It is supposed to work for the T400/T500 as well. The descriptor
@@ -119,7 +119,7 @@ $ make gen-ifd-x200
 
 It will be saved to the `flashregion_0_fd.bin` file.
 
-#### Configuring coreboot
+### Configuring coreboot
 
 Now configure coreboot. You need to select correct chip size and specify paths
 to flash descriptor and gbe dump.
diff --git a/Documentation/mainboard/starlabs/common/building.md b/Documentation/mainboard/starlabs/common/building.md
index 3b9b568b74..c283ef54ef 100644
--- a/Documentation/mainboard/starlabs/common/building.md
+++ b/Documentation/mainboard/starlabs/common/building.md
@@ -1,15 +1,15 @@
-## Building coreboot
+# Building coreboot
 
-### Preliminaries
+## Preliminaries
 
 Prior to building coreboot the following files are required:
 
-#### StarBook series:
+### StarBook series:
 * Intel Flash Descriptor file (descriptor.bin)
 * Intel Management Engine firmware (me.bin)
 * ITE Embedded Controller firmware (ec.bin)
 
-#### StarLite series:
+### StarLite series:
 * Intel Flash Descriptor file (descriptor.bin)
 * IFWI Image (ifwi.rom)
 
@@ -18,7 +18,7 @@ The files listed below are optional:
 
 These files exist in the correct location in the [StarLabsLtd/blobs](https://github.com/StarLabsLtd/blobs) repo on GitHub which is used in place of the standard 3rdparty/blobs repo.
 
-### Build
+## Build
 
 The following commands will build a working image, where the last two words represent the
 series and processor i.e. `lite_glkr`:
diff --git a/Documentation/mainboard/starlabs/common/flashing.md b/Documentation/mainboard/starlabs/common/flashing.md
index c5764b9d6d..46b98afeae 100644
--- a/Documentation/mainboard/starlabs/common/flashing.md
+++ b/Documentation/mainboard/starlabs/common/flashing.md
@@ -1,6 +1,6 @@
 # Flashing with fwupd
 
-#### **Requirements:**
+## **Requirements:**
 
 * fwupd version 1.5.6 or later
 * The battery must be charged to at least 30%
@@ -44,7 +44,7 @@ BIOS Lock must be disabled when switching from the standard AMI (American Megatr
 
 4\. Next, press the `F10` key to **Save & Exit** and then `Enter` to confirm.
 
-#### **Switching Branch**
+## **Switching Branch**
 
 Switching branch refers to changing from AMI firmware to coreboot, or vice versa.
 
diff --git a/Documentation/releases/coreboot-24.02-relnotes.md b/Documentation/releases/coreboot-24.02-relnotes.md
index f82a6a8af5..4b98d57eb8 100644
--- a/Documentation/releases/coreboot-24.02-relnotes.md
+++ b/Documentation/releases/coreboot-24.02-relnotes.md
@@ -12,7 +12,7 @@ optimization.
 The next release is scheduled for mid-May.
 
 
-### Release number format update
+## Release number format update
 
 The previous release was the last to use the incrementing 4.xx release
 name scheme. For this and future releases, coreboot has switched to a
@@ -22,7 +22,7 @@ of 00 implied. If we need to do a fix or incremental release, we'll
 append the values .01, .02 and so on to the initial release value.
 
 
-### The master branch is being deleted
+## The master branch is being deleted
 
 The coreboot project changed from master to main roughly 6 months ago,
 and has been keeping the two branches in sync since then to ease the
@@ -197,8 +197,7 @@ Significant Known and Open Issues
   the version of verstage used in coreboot 24.02.
 
 
-## Issues from the coreboot bugtracker: https://ticket.coreboot.org/
-
+Issues from the coreboot bugtracker: https://ticket.coreboot.org/
 
 ### coreboot-wide or architecture-wide issues
 
diff --git a/Documentation/releases/coreboot-4.21-relnotes.md b/Documentation/releases/coreboot-4.21-relnotes.md
index 5e493b567f..05d334f5d1 100644
--- a/Documentation/releases/coreboot-4.21-relnotes.md
+++ b/Documentation/releases/coreboot-4.21-relnotes.md
@@ -13,7 +13,7 @@ about the coreboot project. There have been a number of new companies
 starting to use coreboot recently, and we appreciate all of the
 contributions and support.
 
-### Upcoming switch from master branch to main branch
+## Upcoming switch from master branch to main branch
 
 Historically, the initial branch that was created in a new git
 repository was named ‘master’. In line with many other projects,
diff --git a/Documentation/releases/coreboot-4.22-relnotes.md b/Documentation/releases/coreboot-4.22-relnotes.md
index a36bc81ce9..8d0cc7a747 100644
--- a/Documentation/releases/coreboot-4.22-relnotes.md
+++ b/Documentation/releases/coreboot-4.22-relnotes.md
@@ -11,7 +11,7 @@ releases, this one reflects a commitment to open source innovation,
 security enhancements, and expanding hardware support.
 
 
-### 4.22.01 release
+## 4.22.01 release
 
 The week between tagging a release and announcing it publicly is used
 to test the tagged version and make sure everything is working as we
@@ -22,7 +22,7 @@ For the 4.22 release cycle we found an uninitialized variable error on
 the sandybridge/ivybridge platforms and rolled that into the 4.22.01
 release package.
 
-### coreboot version naming update
+## coreboot version naming update
 
 This release is the last release to use the incrementing 4.xx release
 name scheme. For future releases, coreboot is switching to a
@@ -33,7 +33,7 @@ the 24.02 release, we'll append the values .01, .02 and so on to the
 initial release value.
 
 
-### coreboot default branch update
+## coreboot default branch update
 
 Immediately after the 4.21 release, the coreboot project changed the
 default git branch from 'master' to 'main'. For the first couple of
diff --git a/Documentation/soc/intel/cse_fw_update/cse_fw_update.md b/Documentation/soc/intel/cse_fw_update/cse_fw_update.md
index 54a5e615c8..ec797e298b 100644
--- a/Documentation/soc/intel/cse_fw_update/cse_fw_update.md
+++ b/Documentation/soc/intel/cse_fw_update/cse_fw_update.md
@@ -1,4 +1,4 @@
-CSE FW update mechanism for devices in field
+# CSE FW update mechanism for devices in field
 
 ## Introduction
 
diff --git a/Documentation/tutorial/part1.md b/Documentation/tutorial/part1.md
index bba00d5f77..88be6fff0b 100644
--- a/Documentation/tutorial/part1.md
+++ b/Documentation/tutorial/part1.md
@@ -86,7 +86,7 @@ make -C payloads/coreinfo
 
 ### Step 5 - Configure the build
 
-##### Configure your mainboard
+#### Configure your mainboard
 
 ```Bash
 make menuconfig
@@ -104,7 +104,7 @@ select < Exit >
 These should be the default selections, so if anything else was set, run
 `make distclean` to remove your old config file and start over.
 
-##### Optionally use your system toolchain (Again, not recommended)
+#### Optionally use your system toolchain (Again, not recommended)
 
 ```Text
 select 'General Setup' menu
@@ -112,7 +112,7 @@ select 'Allow building with any toolchain'
 select < Exit >
 ```
 
-##### Select the payload
+#### Select the payload
 
 ```Text
 select 'Payload' menu
@@ -125,7 +125,7 @@ select < Exit >
 select < Yes >
 ```
 
-##### Check your configuration (optional step):
+#### Check your configuration (optional step):
 
 ```Bash
 make savedefconfig
diff --git a/Documentation/util/abuild/index.md b/Documentation/util/abuild/index.md
index 4def2f6a49..31a267e1e5 100644
--- a/Documentation/util/abuild/index.md
+++ b/Documentation/util/abuild/index.md
@@ -14,7 +14,7 @@ to make sure your patch compiles cleanly for all.
 Note that abuild is a tool to do a simple build test, and binaries it
 produces may well not boot if flashed to a system.
 
-### Basic usage
+## Basic usage
 
 abuild needs to be run from the coreboot directory. If you cd into the
 coreboot/util/abuild directory and try to run it from there, it will
@@ -30,7 +30,7 @@ example, to build the Lenovo X230 target, run:
 $ util/abuild/abuild -t lenovo/x230
 ```
 
-### Where builds and logs are stored
+## Where builds and logs are stored
 
 The resulting images and logs are stored in directory coreboot-builds/
 under your current directory. This can be overridden with --outdir:
@@ -53,7 +53,7 @@ coreboot-builds/passing_boards and coreboot-builds/failing_boards.
 **These logs are overwritten with each abuild run.** Save them elsewhere
 if you feel a need to reference the results later.
 
-### Payloads
+## Payloads
 
 You can also specify a payload directory with -p:
 
@@ -81,7 +81,7 @@ You can also tell abuild not to use a payload:
 util/abuild/abuild -t lenovo/x230 -p none
 ```
 
-### Build non-default configurations
+## Build non-default configurations
 
 Sometimes you do need to build test a custom, non-default configuration.
 This can be accomplished by placing a config file in configs/.
@@ -142,7 +142,7 @@ a file named `myconfig` with this line:
 and run `abuild -K myconfig` to build everything with a silent postcar
 stage.
 
-### Selectively build certain targets only (also config file naming caveats)
+## Selectively build certain targets only (also config file naming caveats)
 
 The P8Z77-M PRO example above would fail for P8Z77-M, because the
 config file name is ambiguous. `abuild` would pick up this config when
@@ -166,7 +166,7 @@ util/abuild/abuild --skip_unset USE_NATIVE_RAMINIT
 This example skips building configs not using (Sandy/Ivy Bridge) native
 RAM init.
 
-### Additional Examples
+## Additional Examples
 
 Many boards have multiple variants. You can build for a specific
 variant of a board:
@@ -203,7 +203,7 @@ Of course, the real power of abuild is in testing multiple boards.
 util/abuild/abuild -B -y -c 8 -p none
 ```
 
-### Full options list
+## Full options list
 
 ```text
 coreboot autobuild v0.11.01 (Feb 3, 2023)
diff --git a/Documentation/util/intelp2m/index.md b/Documentation/util/intelp2m/index.md
index 6873c1b1ea..98b9c009d6 100644
--- a/Documentation/util/intelp2m/index.md
+++ b/Documentation/util/intelp2m/index.md
@@ -11,7 +11,7 @@ make
 ./intelp2m -file /path/to/inteltool.log
 ```
 
-### Platforms
+## Platforms
 
 It is possible to use templates for parsing inteltool.log files.
 To specify such a pattern, use the option `-t <template number>`.
@@ -51,13 +51,13 @@ platform type is set using the -p option (Sunrise by default):
 ./intelp2m -p <platform> -file path/to/inteltool.log
 ```
 
-### Packages
+## Packages
 
 ![][pckgs]
 
 [pckgs]: gopackages.png
 
-### Bit fields in macros
+## Bit fields in macros
 
 Use the `-fld=cb` option to only generate a sequence of bit fields in
 a new macro:
@@ -71,7 +71,7 @@ _PAD_CFG_STRUCT(GPIO_37, PAD_FUNC(NF1) | PAD_TRIG(OFF) | PAD_TRIG(OFF), \
     PAD_PULL(DN_20K)), /* LPSS_UART0_TXD */
 ```
 
-### Raw DW0, DW1 register value
+## Raw DW0, DW1 register value
 
 To generate the gpio.c with raw PAD_CFG_DW0 and PAD_CFG_DW1 register
 values you need to use the -fld=raw option:
@@ -96,7 +96,7 @@ _PAD_CFG_STRUCT(GPP_A10, 0x44000500, 0x00000000),
 _PAD_CFG_STRUCT(GPP_A10, 0x44000500, 0x00000000),
 ```
 
-### Macro Check
+## Macro Check
 
 After generating the macro, the utility checks all used
 fields of the configuration registers. If some field has been
@@ -115,7 +115,7 @@ PAD_CFG_NF_IOSSTATE_IOSTERM(GPIO_38, UP_20K, DEEP, NF1, HIZCRx1, DISPUPD),
 PAD_CFG_NF_IOSSTATE_IOSTERM(GPIO_39, UP_20K, DEEP, NF1, TxLASTRxE, DISPUPD),
 ```
 
-### Information level
+## Information level
 
 The utility can generate additional information about the bit
 fields of the DW0 and DW1 configuration registers. Using the
@@ -158,7 +158,7 @@ PAD_CFG_NF_IOSSTATE_IOSTERM(GPIO_39, UP_20K, DEEP, NF1, TxLASTRxE, \
     DISPUPD),
 ```
 
-### Ignoring Fields
+## Ignoring Fields
 
 Utilities can generate the _PAD_CFG_STRUCT macro and exclude fields
 from it that are not in the corresponding PAD_CFG_*() macro:
@@ -177,7 +177,7 @@ _PAD_CFG_STRUCT(GPIO_39, PAD_FUNC(NF1) | PAD_RESET(DEEP), \
     PAD_PULL(UP_20K) | PAD_IOSTERM(DISPUPD)),
 ```
 
-### FSP-style macro
+## FSP-style macro
 
 The utility allows one to generate macros that include fsp/edk2-platform
 style bitfields:
@@ -205,6 +205,6 @@ style bitfields:
   GpioPadConfigLock },
 ```
 
-### Supported Chipsets
+## Supported Chipsets
 
   Sunrise PCH, Lewisburg PCH, Apollo Lake SoC, CannonLake-LP SoCs