[doc] Consistently use title and headings
* Add a "title" attribute to make the page title show up in the
generated TOC. (The first heading isn't used there unfortunately.)
* The title serves as "h1" heading, use "h2" headings (`##`) and below
within the document.
Signed-off-by: Philipp Wagner <phw@lowrisc.org>
diff --git a/doc/ug/getting_started_sw.md b/doc/ug/getting_started_sw.md
index f0c2aab..dbf54e2 100644
--- a/doc/ug/getting_started_sw.md
+++ b/doc/ug/getting_started_sw.md
@@ -1,4 +1,6 @@
-# Build Software
+---
+title: Build Software
+---
## Prerequisites
@@ -80,4 +82,4 @@
```
If you do not specify your own toolchain configuration file (using `./meson_init.sh -t`), and `meson_init.sh` cannot find the default configuration in your toolchain, the legacy `toolchain.txt` from the main OpenTitan repository will be used.
-If `TOOLCHAIN_PATH` is set, this will be used to update any paths within the legacy configuration.
\ No newline at end of file
+If `TOOLCHAIN_PATH` is set, this will be used to update any paths within the legacy configuration.
diff --git a/doc/ug/getting_started_verilator.md b/doc/ug/getting_started_verilator.md
index 4efdf56..d9b61a9 100644
--- a/doc/ug/getting_started_verilator.md
+++ b/doc/ug/getting_started_verilator.md
@@ -1,4 +1,6 @@
-# Getting started with Verilator
+---
+title: Getting started with Verilator
+---
## About Verilator
diff --git a/doc/ug/github_notes.md b/doc/ug/github_notes.md
index 22d2b00..e442de0 100644
--- a/doc/ug/github_notes.md
+++ b/doc/ug/github_notes.md
@@ -1,4 +1,6 @@
-# GitHub Notes
+---
+title: GitHub Notes
+---
The OpenTitan source tree is maintained on GitHub in a [monolithic repository](https://github.com/lowRISC/opentitan) called opentitan.
diff --git a/doc/ug/install_instructions/index.md b/doc/ug/install_instructions/index.md
index 0adee47..edb5e11 100644
--- a/doc/ug/install_instructions/index.md
+++ b/doc/ug/install_instructions/index.md
@@ -1,5 +1,6 @@
-# Install Build Requirements
-
+---
+title: Install Build Requirements
+---
## System requirements
diff --git a/doc/ug/otbn_sw.md b/doc/ug/otbn_sw.md
index ee6ff7f..82485a4 100644
--- a/doc/ug/otbn_sw.md
+++ b/doc/ug/otbn_sw.md
@@ -10,16 +10,16 @@
The core of OTBN's instruction set is based on RV32I, the RISC-V base integer instruction set.
As such, we implement the toolchain as a thin wrapper around RISC-V binutils.
-# Assembly format and examples
+## Assembly format and examples
The OTBN ISA and programmer model are described in the [OTBN reference manual]({{< relref "hw/ip/otbn/doc" >}}).
In particular, note that the register `x1` has special stack-like behaviour.
There are some example programs at `sw/otbn/code-snippets`.
These range from simple examples of how to use pseudo-operations up to example cryptographic primitives.
-# The tools
+## The tools
-## Assembler
+### Assembler
The OTBN assembler is called `otbn-as` and can be found at `hw/ip/otbn/util/otbn-as`.
This has the same command line interface as `riscv32-unknown-elf-as` (indeed, it's a wrapper around that program).
@@ -31,7 +31,7 @@
hw/ip/otbn/util/otbn-as -o foo.o foo.S
```
-## Linker
+### Linker
The OTBN linker is called `otbn-ld` and can be found at `hw/ip/otbn/util/otbn-ld`.
This is a thin wrapper around `riscv32-unknown-elf-ld`, but supplies a default linker script that matches the OTBN memory layout.
@@ -44,7 +44,7 @@
hw/ip/otbn/util/otbn-ld -o foo foo0.o foo1.o foo2.o
```
-## Objdump
+### Objdump
To disassemble OTBN code, use `otbn-objdump`, which can be found at `hw/ip/otbn/util/otbn-objdump`.
This wraps `riscv32-unknown-elf-objdump`, but correctly disassembles OTBN instructions when run with the `-d` flag.
diff --git a/doc/ug/vendor_hw.md b/doc/ug/vendor_hw.md
index ba29437..8e33215 100644
--- a/doc/ug/vendor_hw.md
+++ b/doc/ug/vendor_hw.md
@@ -1,4 +1,6 @@
-# Work with hardware code in external repositories
+---
+title: Work with hardware code in external repositories
+---
OpenTitan is not a closed ecosystem: we incorporate code from third parties, and we split out pieces of our code to reach a wider audience.
In both cases, we need to import and use code from external repositories in our OpenTitan code base.
