From 6b1086d94abd48d9216b6b19c8873eb67c294e61 Mon Sep 17 00:00:00 2001
From: Kareem Farid <kareefardi@users.noreply.github.com>
Date: Mon, 15 Jan 2024 13:51:54 +0200
Subject: [PATCH] fix more warnings generated by myst

---
 docs/source/reference/architecture.md      |  3 +-
 docs/source/reference/pin_placement_cfg.md |  2 +-
 docs/source/usage/corners_and_sta.md       |  2 +-
 docs/source/usage/hardening_macros.md      | 74 ++++++++---------
 docs/source/usage/writing_custom_steps.md  | 93 ++++++++++++----------
 openlane/flows/flow.py                     |  3 +-
 openlane/steps/step.py                     |  4 +-
 7 files changed, 96 insertions(+), 85 deletions(-)

diff --git a/docs/source/reference/architecture.md b/docs/source/reference/architecture.md
index 311048d48..de39392f6 100644
--- a/docs/source/reference/architecture.md
+++ b/docs/source/reference/architecture.md
@@ -29,7 +29,8 @@ Steps should align themselves to one principle:
 
 - <u>The same step with the same input configuration and same input state must emit the same output.</u>
 
-<a name="step-strictures"></a> This is applied as far as the functionality goes:
+(ref-step-strictures)=
+This is applied as far as the functionality goes:
 
 - Steps **do NOT** modify files in-place. New files must be created in the step's
   dedicated directory. If the tool does not support out-of-place modification,
diff --git a/docs/source/reference/pin_placement_cfg.md b/docs/source/reference/pin_placement_cfg.md
index d5c4ad391..0398aebfb 100644
--- a/docs/source/reference/pin_placement_cfg.md
+++ b/docs/source/reference/pin_placement_cfg.md
@@ -1,6 +1,6 @@
 # Pin Placer Configuration Files
 
-If you're using the step {ref}`Odb.CustomIOPlacement <odb-customioplacement>`
+If you're using the step {ref}`Odb.CustomIOPlacement <step-odb-customioplacement>`
 the variable `FP_PIN_ORDER_CFG` asks you to create a `.cfg` file that can be used
 to configure this placement step.
 
diff --git a/docs/source/usage/corners_and_sta.md b/docs/source/usage/corners_and_sta.md
index e74e4db5b..93f24a3d3 100644
--- a/docs/source/usage/corners_and_sta.md
+++ b/docs/source/usage/corners_and_sta.md
@@ -80,7 +80,7 @@ The sky130A/sky130_fd_sc_hd SCL, for example, comes with configurations for thes
 | "ss_100C_1v60" | {S, S}               | 1.6         | 100             | `sky130_fd_sc_hd__ss_100C_1v60.lib` |
 | "ff_n40C_1v95" | {F, F}               | 1.95        | -40             | `sky130_fd_sc_hd__ff_n40C_1v95.lib` |
 
-- Interconnect: Corner data stored in {ref}`TECH_LEFS <var-tech_lefs>` and {ref}`RCX_RULESETS <openroad-rcx-var-rcx_rulesets>`
+- Interconnect: Corner data stored in {ref}`TECH_LEFS <var-tech_lefs>` and {ref}`RCX_RULESETS <var-openroad-rcx-rcx_rulesets>`
 
 | Name  | Description                     | Corresponding Technology LEF | Corresponding Ruleset               |
 | ----- | ------------------------------- | ---------------------------- | ----------------------------------- |
diff --git a/docs/source/usage/hardening_macros.md b/docs/source/usage/hardening_macros.md
index 981d0d22f..a72be1e7a 100644
--- a/docs/source/usage/hardening_macros.md
+++ b/docs/source/usage/hardening_macros.md
@@ -38,7 +38,7 @@ The basic configuration `config.json` file for the default flow should at least
 contain these variables:
 
 - [`DESIGN_NAME`](#var-design_name)
-- [`VERILOG_FILES`](#yosys-synthesis-var-verilog_files)
+- [`VERILOG_FILES`](#var-yosys-synthesis-verilog_files)
 - [`CLOCK_PORT`](#var-clock_port)
 
 So, for example:
@@ -60,13 +60,13 @@ Synthesis is the process by which RTL is transformed into logic primitives,
 then again transformed into a list of "standard cells"- silicon patterns.
 
 The default flow uses Yosys for Synthesis, namely,
-[this step](../reference/step_config_vars.md#Yosys.Synthesis).
+[this step](#step-yosys-synthesis)
 
 In general, there's not much to mess around with regards to
 synthesis, but here are some tips for using a couple variables:
 
 - If your macro is huge (200k+ cells), then you might want to try setting
-  [`SYNTH_NO_FLAT`](../reference/step_config_vars.md#Yosys.Synthesis.SYNTH_NO_FLAT)
+  [`SYNTH_NO_FLAT`](#var-yosys-synthesis-synth_no_flat)
   to `1` (Tcl)/`true` (JSON), which will postpone the flattening of the design
   during synthesis until the very end.
 
@@ -85,16 +85,16 @@ the timing constraints on the design are met:
 
 Here are some variables you need to consider:
 
-- [`CLOCK_PORT`](../reference/flow_config_vars.md#CLOCK_PORT): Self-explanatory.
-- [`CLOCK_PERIOD`](../reference/flow_config_vars.md#CLOCK_PERIOD): The value will
+- [`CLOCK_PORT`](#var-clock_port): Self-explanatory.
+- [`CLOCK_PERIOD`](#var-clock_period): The value will
   be used to calculate any timing violations, and also in resizer stages, attempt
   to fix the cells in question. If the clock period could not be reasonably achieved,
-- [`IO_DELAY_CONSTRAINT`](../reference/pdk_config_vars.md#IO_DELAY_CONSTRAINT)
+- [`IO_DELAY_CONSTRAINT`](#var-io_delay_constraint)
 
 You may also want to write a custom SDC file to be used in STA and CTS.
 The default SDC file in the default flow is [this file](../../../openlane/scripts/base.sdc),
 however, you can change that by pointing to a new file with the environment variable
-[`FALLBACK_SDC_FILE`](../reference/step_config_vars.md#Misc.LoadBaseSDC.FALLBACK_SDC_FILE)
+[`FALLBACK_SDC_FILE`](#var-fallback_sdc_file)
 
 Currently, static timing analysis is done:
 
@@ -117,13 +117,13 @@ You have three options for floorplanning in the default flow:
 
 1. Let the tools determine the area relative to the size and number of cells.
 
-- This is done by setting [`FP_SIZING`](../reference/step_config_vars.md#OpenROAD.Floorplan.FP_SIZING)
-  to `relative` (the default value), and setting [`FP_CORE_UTIL`](../reference/step_config_vars.md#OpenROAD.Floorplan.FP_CORE_UTIL)
+- This is done by setting [`FP_SIZING`](#var-openroad-floorplan-fp_sizing)
+  to `relative` (the default value), and setting [`FP_CORE_UTIL`](#var-openroad-floorplan-fp_core_util)
   as the core utilization percentage. You may also the aspect ratio
-  (`1` by default) by changing [`FP_ASPECT_RATIO`](../reference/step_config_vars.md#OpenROAD.Floorplan.FP_ASPECT_RATIO).
+  (`1` by default) by changing [`FP_ASPECT_RATIO`](#var-openroad-floorplan-fp_aspect_ratio).
 
-2. Set a specific die area by setting [`FP_SIZING`](../reference/step_config_vars.md#OpenROAD.Floorplan.FP_SIZING)
-   to `absolute` and setting the [`DIE_AREA` configuration variable](../reference/step_config_vars.md#OpenROAD.Floorplan.DIE_AREA).
+2. Set a specific die area by setting [`FP_SIZING`](#var-openroad-floorplan-fp_sizing)
+   to `absolute` and setting the [`DIE_AREA` configuration variable](#var-die_area).
 
 <!--
 1. Use a template DEF and apply the same dimensions of that DEF file.
@@ -140,7 +140,7 @@ file- not just the floorplan.
 ## PDN Generation
 
 You can find a full list of power distribution network configuration variables
-in the PDN step [here](../reference/step_config_vars.md#power-distribution-network-generation).
+in the PDN step [here](#step-openroad-generatepdn).
 
 Most designs would have to change these values based on the size of the floorplan:
 
@@ -166,7 +166,7 @@ flow:
 1. Letting OpenROAD randomly assign IOs using the random equidistant mode.
    This is the default.
 2. Manually setting the direction of each pin using a configuration file
-   by pointing [`FP_PIN_ORDER_CFG`](../reference/step_config_vars.md#Odb.CustomIOPlacement.FP_PIN_ORDER_CFG)
+   by pointing [`FP_PIN_ORDER_CFG`](#var-odb-customioplacement-fp_pin_order_cfg)
    to point to that file.
 
 <!--
@@ -194,10 +194,10 @@ Placement is done across two stages: "global placement" and "detailed placement"
 ### Global Placement
 
 For a rundown of what global placement does, please see the Global Placement
-step documentation [here](../reference/step_config_vars.md#OpenROAD.GlobalPlacement).
+step documentation [here](#step-openroad-globalplacement).
 
 For global placement, the most important value would be
-[`PL_TARGET_DENSITY_PCT`](../reference/step_config_vars.md#OpenROAD.GlobalPlacement.PL_TARGET_DENSITY_PCT)
+[`PL_TARGET_DENSITY_PCT`](#var-openroad-globalplacement-pl_target_density_pct)
 which should be easy to set as follows:
 
 - If your design is not a tiny design, then `PL_TARGET_DENSITY_PCT`
@@ -212,10 +212,10 @@ which should be easy to set as follows:
     manually setting an appropriate `DIE_AREA`:
     check [the floorplan section](#floorplanning) for more details.
     You may also want to reduce the values for:
-    _ [`FP_PDN_HORIZONTAL_HALO`](../reference/step_config_vars.md#OpenROAD.GeneratePDN.FP_PDN_HORIZONTAL_HALO)
-    _ [`FP_PDN_VERTICAL_HALO`](../reference/step_config_vars.md#OpenROAD.GeneratePDN.FP_PDN_VERTICAL_HALO)
+    _ [`FP_PDN_HORIZONTAL_HALO`](#var-openroad-generatepdn-fp_pdn_horizontal_halo)
+    _ [`FP_PDN_VERTICAL_HALO`](#var-openroad-generatepdn-fp_pdn_vertical_halo)
 
-There is also [`GPL_CELL_PADDING`](../reference/step_config_vars.md#OpenROAD.GlobalPlacement.GPL_CELL_PADDING).
+There is also [`GPL_CELL_PADDING`](#var-gpl_cell_padding).
 This will treat cells as "wider" than they are, which has an impact on routing
 and diode insertion. If you increase the padding, make sure to recalculate the
 `PL_TARGET_DENSITY_PCT` as such: {math}`util \approx FP\_CORE\_UTIL + 10 + 5 * GPL\_CELL\_PADDING`.
@@ -223,16 +223,16 @@ and diode insertion. If you increase the padding, make sure to recalculate the
 ### Detailed Placement
 
 For a rundown of what detailed placement does, please see the Detailed Placement
-step documentation [here](../reference/step_config_vars.md#OpenROAD.DetailedPlacement).
+step documentation [here](#step-openroad-detailedplacement).
 
 The only value to consider here is the
-[`DPL_CELL_PADDING`](../reference/step_config_vars.md#OpenROAD.GlobalPlacement.DPL_CELL_PADDING),
+[`DPL_CELL_PADDING`](#var-dpl_cell_padding),
 which must be less than or equal to the `DPL_CELL_PADDING` specified above.
 
 ## Clock Tree Synthesis
 
 It's fine to leave values as defaults for clock tree synthesis most of the time:
-see the step [`OpenROAD.CTS`](../reference/step_config_vars.md#OpenROAD.CTS) for
+see the step [`OpenROAD.CTS`](#step-openroad-cts) for
 more info.
 
 Clock tree synthesis takes some time compared to other steps you've encountered
@@ -250,8 +250,8 @@ best left as is.
 
 Routing in general goes through these phases:
 
-- **Global Routing**: Using [`OpenROAD.GlobalRouting`](../reference/step_config_vars.md#OpenROAD.GlobalRouting)
-- **Detailed Routing**: Using [`OpenROAD.DetailedRouting`](../reference/step_config_vars.md#OpenROAD.DetailedRouting)
+- **Global Routing**: Using [`OpenROAD.GlobalRouting`](#step-openroad-globalrouting)
+- **Detailed Routing**: Using [`OpenROAD.DetailedRouting`](#step-openroad-detailedrouting)
 
 The subsections include some notes:
 
@@ -260,16 +260,16 @@ The subsections include some notes:
 To help mitigate the antenna effect, after Global Placement there are also three
 other steps you may choose to enable:
 
-- [`Odb.DiodesOnPorts`](../reference/step_config_vars.md#Odb.DiodesOnPorts):
+- [`Odb.DiodesOnPorts`](#step-odb-diodesonports):
   Unconditionally inserts diodes on design ports. This is helpful for hardening
   macros, where you don't know how long the wires external to the macro are
   going to be. Requires {math}`GPL\_CELL\_PADDING \ge 2`.
-- [`Odb.HeuristicDiodeInsertion`](../reference/step_config_vars.md#Odb.HeuristicDiodeInsertion):
+- [`Odb.HeuristicDiodeInsertion`](#step-odb-heuristicdiodeinsertion):
   Inserts diodes based on the virtual wire length, s.t. nets longer than
   a specific threshold get a diode inserted by default. Disabled by default, but
   can be enabled by setting flow config variable `RUN_HEURISTIC_DIODE_INSERTION` to `true`.
   Requires {math}`GPL\_CELL\_PADDING \ge 2`.
-- [`OpenROAD.RepairAntennas`](../reference/step_config_vars.md#OpenROAD.RepairAntennas):
+- [`OpenROAD.RepairAntennas`](#step-openroad-repairantennas):
   Uses a more advanced antenna repair algorithm built into OpenROAD. Enabled by
   default, can be disabled by setting flow config variable `RUN_ANTENNA_REPAIR`
   to `false`.
@@ -279,7 +279,7 @@ other steps you may choose to enable:
 By default, detailed routing, which is the most computationally expensive step
 in the flow, will use all available threads on your computer by default.
 You can decrease that by overriding the step variable
-[`DRT_THREADS`](../reference/step_config_vars.md#OpenROAD.DetailedRouting.DRT_THREADS).
+[`DRT_THREADS`](#var-openroad-detailedrouting-drt_threads).
 
 Be advised that higher is always better for runtime.
 
@@ -290,8 +290,8 @@ final view, and it is the one submitted to foundries for manufacturing.
 
 The default flow tapes out GDSII from LEF/DEF using two tools:
 
-- [Magic](http://opencircuitdesign.com/magic/): Using [`Magic.StreamOut`](../reference/step_config_vars.md#Magic.StreamOut)
-- [KLayout](http://klayout.de): Using [`KLayout.StreamOut`](../reference/step_config_vars.md#KLayout.StreamOut)
+- [Magic](http://opencircuitdesign.com/magic/): Using [`Magic.StreamOut`](#step-magic-streamout)
+- [KLayout](http://klayout.de): Using [`KLayout.StreamOut`](#step-klayout-streamout)
 
 The idea is, if there's any difference between the two GDSII views, one tool
 is misconfigured or the LEF/DEF contains some ambiguity: at any rate, the design
@@ -300,11 +300,11 @@ the two, please [file an issue](https://github.com/efabless/openlane2/issues/new
 and we will investigate.
 
 The difference is a simple geometric XOR run using KLayout,
-using the [`KLayout.XOR` step](../reference/step_config_vars.md#KLayout.XOR).
+using the [`KLayout.XOR` step](#step-klayout-xor).
 
 If the PDK does not support one of the two tools, that tool will not run, and
 attempting the XOR may interrupt the flow: it is thus a good idea to set
-[`RUN_KLAYOUT_XOR`](../reference/step_config_vars.md#Layout.XOR.RUN_KLAYOUT_XOR)
+[`RUN_KLAYOUT_XOR`](#var-classic-run_klayout_xor)
 to `false`.
 
 ## Signoff
@@ -314,7 +314,7 @@ electrical checks on the final design.
 
 ### Design Rule Checking
 
-Design Rule Checking (DRC) is done using Magic, specifically the [`Magic.DRC` step](../reference/step_config_vars.md#Magic.DRC).
+Design Rule Checking (DRC) is done using Magic, specifically the [`Magic.DRC` step](#step-magic-drc).
 
 Designs with design rule violations are not accepted for manufacturing by any foundry.
 
@@ -327,7 +327,7 @@ LEF/DEF in all other cases:
   designs.
 
 You can specify your favored method using the config var
-[`MAGIC_DRC_USE_GDS`](../reference/step_config_vars.md#Magic.DRC.MAGIC_DRC_USE_GDS).
+[`MAGIC_DRC_USE_GDS`](#var-magic-drc-magic_drc_use_gds).
 
 If your LEF/DEF DRC fails, it is recommended to run the `GDS` check as well just
 to verify that it's not abstraction issue; you can do this as follows:
@@ -350,11 +350,11 @@ It verifies the following:
 - There are no unexpected opens in the final layout.
 - All signals are connected correctly.
 
-The SPICE extraction is done using [this step](../reference/step_config_vars.md#Magic.SpiceExtraction),
-and the LVS extraction is done using [this one](../reference/step_config_vars.md#Magic.LVS).
+The SPICE extraction is done using [this step](#step-magic-spiceextraction),
+and the LVS extraction is done using [this one](#step-netgen-lvs).
 
 ```{note}
-Like GDS, the variable [`MAGIC_EXT_USE_GDS`](../reference/step_config_vars.md#Magic.SpiceExtraction.MAGIC_EXT_USE_GDS),
+Like GDS, the variable [`MAGIC_EXT_USE_GDS`](#var-magic-spiceextraction-magic_ext_use_gds),
 and the same consideration applies. Use your best judgment.
 ```
 
diff --git a/docs/source/usage/writing_custom_steps.md b/docs/source/usage/writing_custom_steps.md
index e56d80304..eeb909d09 100644
--- a/docs/source/usage/writing_custom_steps.md
+++ b/docs/source/usage/writing_custom_steps.md
@@ -1,19 +1,21 @@
 # Writing Custom Steps
+
 Just like you may write custom flows, you may also write custom steps to run
 within those flows.
 
-***Again***, please review OpenLane's high-level architecture [at this link](../reference/architecture.md).
+**_Again_**, please review OpenLane's high-level architecture [at this link](../reference/architecture.md).
 This defines many of the terms used and enumerates strictures mentioned in this document.
 
 ## Generic Steps
+
 Like flows, each Step subclass must:
 
-* Implement the {meth}`openlane.steps.Step.run` method.
-    * This step is responsible for the core logic of the step, which is arbitrary.
-    * This method must return two values:
-      * A `ViewsUpdate`, a dictionary from {class}`DesignFormat` objects to
-        Paths for all views altered.
-      * A `MetricsUpdate`, a dictionary with valid JSON values.
+- Implement the {meth}`openlane.steps.Step.run` method.
+  - This step is responsible for the core logic of the step, which is arbitrary.
+  - This method must return two values:
+    - A `ViewsUpdate`, a dictionary from {class}`DesignFormat` objects to
+      Paths for all views altered.
+    - A `MetricsUpdate`, a dictionary with valid JSON values.
 
 ```{important}
 Do NOT call the `run` method of any `Step` from outside of `Step` and its
@@ -25,53 +27,54 @@ You should not be overriding `start` either, which is marked **final**.
 
 But also, each Step is required to:
 
-* Declare any required {class}`openlane.state.State` inputs in the `inputs`
+- Declare any required {class}`openlane.state.State` inputs in the `inputs`
   attribute.
-    * This will enforce checking the input states for these views.
-* Declare any potential state modifications in the `outputs` attribute.
-    * This list is checked for completeness and validity- i.e. the {class}`Step`
+  - This will enforce checking the input states for these views.
+- Declare any potential state modifications in the `outputs` attribute.
+  - This list is checked for completeness and validity- i.e. the {class}`Step`
     superclass WILL throw a `StepException` if a Step modifies any State variable
     it does not declare.
-* Declare any used configuration variables in the `config_vars` attribute.
+- Declare any used configuration variables in the `config_vars` attribute.
 
 ```{important}
-Don't forget the [`Step` strictures](../reference/architecture.md#step-strictures).
+Don't forget the [`Step` strictures](#ref-step-strictures).
 Some of them are programmatically enforced, but are still not.
 ```
 
 ### Writing Config Variables
+
 Config variables are declared using the {class}`openlane.config.Variable` object.
 
 There are some conventions to writing these variables.
 
-* Variable names are declared in `UPPER_SNAKE_CASE`, and must be valid identifiers
+- Variable names are declared in `UPPER_SNAKE_CASE`, and must be valid identifiers
   in the Python programming language.
-* Composite types should be declared using the `typing` module, i.e., for a list
+- Composite types should be declared using the `typing` module, i.e., for a list
   of strings, try `typing.List[str]` instead of `list[str]` or just `list`.
-  * `list[str]` is incompatible with Python 3.8.
-  * `list` does not give OpenLane adequate information to validate the child
-  variables.
-* Variables that capture a physical quantity, such as time, distance or similar,
+  - `list[str]` is incompatible with Python 3.8.
+  - `list` does not give OpenLane adequate information to validate the child
+    variables.
+- Variables that capture a physical quantity, such as time, distance or similar,
   must declare units using their `"units"` field.
-  * In case of micro-, the only SI prefix denoted with a non-latin letter, use this
+  - In case of micro-, the only SI prefix denoted with a non-latin letter, use this
     exact unicode codepoint: `µ`
-* Variables may be declared as `pdk`, which determines the compatibility of a PDK
+- Variables may be declared as `pdk`, which determines the compatibility of a PDK
   with your step. If you use a PDK that does not declare one of your declared PDK
   variables, the configuration will not compile and the step will raise a
   {class}`openlane.steps.StepException`.
-  * PDK variables should generally avoid having default values other than ``None``.
+  - PDK variables should generally avoid having default values other than `None`.
     An exception is when a quantity may be defined by some PDKs, but needs a fallback
     value for others.
-* No complex defaults. Defaults must be scalar and quick to evaluate- if your
+- No complex defaults. Defaults must be scalar and quick to evaluate- if your
   default value depends on the default value of another variable, for example,
-* All filesystem paths must be declared as {class}`openlane.common.Path`, objects
+- All filesystem paths must be declared as {class}`openlane.common.Path`, objects
   which adds some very necessary validation and enables easier processing of the
   variables down the line.
-  * Avoid pointing to entire folders. If your step may require multiple files within
+  - Avoid pointing to entire folders. If your step may require multiple files within
     a folder, try using the type `List[Path]`.
 
-
 ### Implementing `run`
+
 The run header should look like this:
 
 ```python
@@ -82,8 +85,8 @@ The `*args` and `**kwargs` allow subclasses to pass arguments to subprocesses-
 more on that later.
 
 You can access configuration variables- which are validated by this point- using
- `self.config[KEY]`. If you need to save files, you can get the step directory
- using `self.step_dir`. For example:
+`self.config[KEY]`. If you need to save files, you can get the step directory
+using `self.step_dir`. For example:
 
 ```python
 design_name = self.config["DESIGN_NAME"]
@@ -94,7 +97,7 @@ output_path = os.path.join(self.step_dir, f"{design_name}.def")
 A step has access to:
 
 * Its declared `config_vars`
-* [All Common Flow Variables](../reference/flows.md#universal-flow-configuration-variables)
+* [All Common Flow Variables](../reference/common_flow_vars.md#universal-flow-configuration-variables)
 
 Attempting to access any other variable is undefined behavior.
 ```
@@ -107,9 +110,9 @@ will handle this check for you.
 
 Otherwise, you're basically free to write any logic you desire, with one exception:
 
-* If you're running a terminal subprocess you'd like to have OpenLane manage the
+- If you're running a terminal subprocess you'd like to have OpenLane manage the
   logs for, please use {meth}`openlane.steps.Step.run_subprocess`,
-  passing *args and **kwargs. It will manage
+  passing \*args and \*\*kwargs. It will manage
   I/O for the process, and allow the creation of report files straight from the
   logs- more on that later.
 
@@ -117,12 +120,14 @@ In the end, add any views updated to the first dictionary in the returned tuple,
 and any metrics updated to the second dictionary in the returned tuple.
 
 ## Creating Reports
+
 You can create report files manually in Python, but if you're running a subprocess,
 you can also write `%OL_CREATE_REPORT <name>.rpt` to stdout and everything until
 `%OL_END_REPORT` (or another `%OL_CREATE_REPORT`) will be forwarded to a file called
 `<name>.rpt` in the step dir automatically.
 
 ## Creating Metrics
+
 Likewise, if you're running a subprocess, you can have {meth}`openlane.steps.Step.run_subprocess`
 capture them for you automatically by using `%OL_METRIC`. See the documentation
 of {meth}`openlane.steps.Step.run_subprocess` for more info.
@@ -135,23 +140,26 @@ invocations and add any values to the returned `MetricUpdate` dictionary as appr
 ```
 
 ## Tool-Specific Steps
+
 The `Step` object makes heavy use of object-oriented programming to encourage
 as much code reuse as possible. To that extent, there exists some more specialized
 `Step` abstract base classes that deal with specific utilities:
 
-### {class}`openlane.steps.TclStep` 
+### {class}`openlane.steps.TclStep`
+
 `TclStep` implements a `run` that works for most Tcl-based utilities.
 This run calls a subprocess with the value of {meth}`openlane.steps.TclStep.get_command`,
 and it emplaces all configuration variables as environment variables using this scheme:
 
-* List variables are joined with a space character.
-* Enumerations are replaced with the enumeration name.
-* Booleans are replaced with `"1"` if true or `"0"` if false.
-* Integers and Decimals are turned into Base-10 strings.
+- List variables are joined with a space character.
+- Enumerations are replaced with the enumeration name.
+- Booleans are replaced with `"1"` if true or `"0"` if false.
+- Integers and Decimals are turned into Base-10 strings.
 
 The state is also exposed to the TclStep as is:
-* Input files are pointed to in variables with the format `CURRENT_<view name>`.
-* Output paths are pointed to in the variables with the format `SAVE_<view name>`.
+
+- Input files are pointed to in variables with the format `CURRENT_<view name>`.
+- Output paths are pointed to in the variables with the format `SAVE_<view name>`.
 
 If a TclStep-based step fails, a reproducible is created, which can be submitted
 to the respective repository of the tool.
@@ -160,11 +168,12 @@ Keep in mind that TclStep-based tools still have to define their `config_vars`,
 `inputs` and `outputs`.
 
 #### Subclasses
+
 `TclStep` has various subclasses for a number of Tcl-based utilities:
 
-* {class}`openlane.steps.OpenROADStep`
-* {class}`openlane.steps.YosysStep`
-* {class}`openlane.steps.MagicStep`
+- {class}`openlane.steps.OpenROADStep`
+- {class}`openlane.steps.YosysStep`
+- {class}`openlane.steps.MagicStep`
 
 These subclasses acts as an abstract base class for steps that use their
 respective utility. They have one abstract method, `get_script_path`.
@@ -179,4 +188,4 @@ config_vars = OpenROADStep.config_vars + [
 ]
 ```
 
-Be sure to read the subclass's `run` docstring as they may contain critical information.
\ No newline at end of file
+Be sure to read the subclass's `run` docstring as they may contain critical information.
diff --git a/openlane/flows/flow.py b/openlane/flows/flow.py
index 86b44374a..8855ae0af 100644
--- a/openlane/flows/flow.py
+++ b/openlane/flows/flow.py
@@ -332,6 +332,7 @@ def get_help_md(Self) -> str:  # pragma: no cover
         result = (
             textwrap.dedent(
                 f"""\
+                (flow-{Self.name})=
                 ### {Self.__name__}
 
                 ```{{eval-rst}}
@@ -371,7 +372,7 @@ def get_help_md(Self) -> str:  # pragma: no cover
             for var in flow_config_vars:
                 units = var.units or ""
                 pdk_superscript = "<sup>PDK</sup>" if var.pdk else ""
-                result += f'| <a name="{Self.__name__.lower()}.{var.name.lower()}"></a>`{var.name}`{pdk_superscript} | {var.type_repr_md()} | {var.desc_repr_md()} | `{var.default}` | {units} |\n'
+                result += f"| `{var.name}`{{#var-{Self.__name__.lower()}-{var.name.lower()}}}{pdk_superscript} | {var.type_repr_md()} | {var.desc_repr_md()} | `{var.default}` | {units} |\n"
             result += "\n"
 
         if len(Self.Steps):
diff --git a/openlane/steps/step.py b/openlane/steps/step.py
index 0a280a6ce..5f03332f7 100644
--- a/openlane/steps/step.py
+++ b/openlane/steps/step.py
@@ -516,13 +516,13 @@ def get_help_md(
             for var in Self.config_vars:
                 units = var.units or ""
                 pdk_superscript = "<sup>PDK</sup>" if var.pdk else ""
-                result += f"| `{var.name}`{{#{slugify(Self.id.lower())}-var-{var.name.lower()}}}{pdk_superscript} | {var.type_repr_md()} | {var.desc_repr_md()} | `{var.default}` | {units} |\n"
+                result += f"| `{var.name}`{{#var-{slugify(Self.id.lower())}-{var.name.lower()}}}{pdk_superscript} | {var.type_repr_md()} | {var.desc_repr_md()} | `{var.default}` | {units} |\n"
             result += "\n"
 
         result = (
             textwrap.dedent(
                 f"""
-                ({slugify(Self.id.lower())})=
+                (step-{slugify(Self.id.lower())})=
                 ### {Self.__get_desc()}
                 """
             )