refactor(docs): port entire documentation from mkdocs to hugo

docs/archetypes/default.md

@@ -0,0 +1,5 @@
++++
+title = '{{ replace .File.ContentBaseName "-" " " | title }}'
+date = {{ .Date }}
+draft = true
++++

docs/content/main/dev_docs/coding_style.md

@@ -0,0 +1,8 @@
++++
+title = 'Coding Style'
+weight = 25
++++
+
+{{< callout warning "Documentation Moved" >}}
+This documentation has been relocated to [Getting Started -> Code Standards](../getting_started/code_standards.md). Please use the new location for the most up-to-date information.
+{{< /callout >}}

docs/dev/configurations.md → docs/content/main/dev_docs/configurations.md

@@ -1,4 +1,7 @@
-# Managing Configurations
++++
+title = 'Managing Configurations'
+weight = 5
++++ 
 
 Configurations are managed by the `config` package. It provides both environment and application configurations.
 

docs/dev/deps_and_packaging.md → docs/content/main/dev_docs/deps_and_packaging.md

@@ -1,27 +1,30 @@
-# EEST Dependency Management and Packaging
++++
+title = 'Dependency Management and Packaging'
+weight = 45
++++
 
 EEST uses [`uv`](https://docs.astral.sh/uv/) to manage and pin its dependencies.
 
-Please use `uv>=0.7.0` to ensure `uv` writes `uv.lock` files with consistent fields and formatting (see [ethereum/execution-spec-tests#1597]https://github.com/ethereum/execution-spec-tests/pull/1597).
+Please use `uv>=0.7.0` to ensure `uv` writes `uv.lock` files with consistent fields and formatting (see [ethereum/execution-spec-tests#1597](https://github.com/ethereum/execution-spec-tests/pull/1597)).
 
 ## Managing Dependencies
 
 We aim to provide specific [version specifiers](https://peps.python.org/pep-0440/#version-specifiers) for each of our direct and extra dependencies.
 
-!!! note "Packages should be managed via `uv`"
+{{< callout info "Packages should be managed via `uv`" >}}
+Dependencies should be managed using `uv` on the command-line to ensure that version compatibility is ensured across all dependencies and that `uv.lock` is updated as required.
 
-    Dependencies should be managed using `uv` on the command-line to ensure that version compatibility is ensured across all dependencies and that `uv.lock` is updated as required.
+The docs below cover common operations, see the `uv` [documentation on managing dependencies](https://docs.astral.sh/uv/concepts/projects/dependencies/#multiple-sources) for more information.
+{{< /callout >}}
 
-    The docs below cover common operations, see the `uv` [documentation on managing dependencies](https://docs.astral.sh/uv/concepts/projects/dependencies/#multiple-sources) for more information.
+{{< callout info "Separate PRs are preferred when managing dependencies" >}}
+An upgrade of all pinned dependencies in `uv.lock` must be performed in a dedicated PR!
 
-!!! info "Separate PRs are preferred when managing dependencies"
+For other dependency changes, they can be included in the PR that removed use of the library, for example. But if a version bump is made, without related source code changes, it should be done in a dedicated PR. This makes the change:
 
-    An upgrade of all pinned dependencies in `uv.lock` must be performed in a dedicated PR!
-
-    For other dependency changes, they can be included in the PR that removed use of the library, for example. But if a version bump is made, without related source code changes, it should be done in a dedicated PR. This makes the change:
-
-    - Easier to track.
-    - Trivial to revert.
+- Easier to track.
+- Trivial to revert.
+{{< /callout >}}
 
 ### Adding/modifying direct dependencies
 
@@ -45,17 +48,17 @@ ethereum-spec-evm-resolver = { git = "https://github.com/petertdavies/ethereum-s
 ...
 ```
 
-!!! example "Example: Updating direct dependencies"
-
-    Example of a package dependency update:
-    ```console
-    uv add "requests>=2.31,<2.33"
-    ```
+{{< callout info "Example: Updating direct dependencies" >}}
+Example of a package dependency update:
+```console
+uv add "requests>=2.31,<2.33"
+```
 
-    Example of a source dependency update:
-    ```console
-    uv add "ethereum-spec-evm-resolver @ git+https://github.com/petertdavies/ethereum-spec-evm-resolver@623ac4565025e72b65f45b926da2a3552041b469"
-    ```
+Example of a source dependency update:
+```console
+uv add "ethereum-spec-evm-resolver @ git+https://github.com/petertdavies/ethereum-spec-evm-resolver@623ac4565025e72b65f45b926da2a3552041b469"
+```
+{{< /callout >}}
 
 ### Adding/modifying optional dependencies
 
@@ -74,11 +77,11 @@ docs = [
 ]
 ```
 
-!!! example "Example: Updating an optional dependency"
-
-    ```
-    uv add --optional lint "types-requests>=2.31,<2.33"
-    ```
+{{< callout info "Example: Updating an optional dependency" >}}
+```
+uv add --optional lint "types-requests>=2.31,<2.33"
+```
+{{< /callout >}}
 
 ## Upgrading Pinned Dependencies in `uv.lock`
 

docs/content/main/dev_docs/docs.md

@@ -0,0 +1,36 @@
++++
+title = 'Documentation'
+weight = 15
++++
+
+The `execution-spec-tests` documentation is generated via [`hugo`](https://github.com/gohugoio/hugo) and hosted remotely on Github Pages at [eest.ethereum.org](https://eest.ethereum.org/).
+
+## Prerequisites
+
+Grab the latest `hugo` binary from the official release page or build it yourself. Then make the binary executable and add it to the PATH (or to a directory that has already been added to the PATH like e.g. `/usr/local/bin/`). We do not require any additional plugins or dependencies.
+
+## Build and Locally Host the Documentation
+
+Build the docs:
+
+```console
+hugo
+```
+
+If you want to build + locally host the docs:
+
+```console
+hugo server
+```
+
+## Remote Deployment and Versioning
+
+The execution-specs-test docs are hosted using Github pages at [eest.ethereum.org](https://eest.ethereum.org/). Versions are updated/deployed automatically as part of Github Actions.
+
+### CI/CD: Doc Deployment via Github Actions
+
+This is our workflow that automatically deploys updated/new versions of the docs:
+
+| Workflow `yaml` File | What | When |
+|----------------------|------|------|
+| `docs.yaml`     | Deploy new version of docs

docs/dev/documenting_clis.md → docs/content/main/dev_docs/documenting_clis.md

@@ -1,4 +1,7 @@
-# Documenting CLIs
++++
+title = 'Documenting CLI Commands'
+weight = 20
++++
 
 EEST command line interfaces (CLIs) are documented using the [`click`](https://click.palletsprojects.com) library's built-in help system and the [`mkdocs-click`](https://github.com/mkdocs/mkdocs-click) extension for mkdocs. This allows generation of CLI documentation directly from the (click) source code, ensuring that the documentation is always up-to-date with the code.
 

docs/dev/interactive_usage.md → docs/content/main/dev_docs/interactive_usage.md

@@ -1,4 +1,7 @@
-# Working with EEST Libraries Interactively
++++
+title = 'Interactive Library Usage'
+weight = 10
++++
 
 You can work with EEST Python packages interactively with `ipython` using:
 
@@ -8,16 +11,16 @@ uvx  --with-editable . ipython
 
 This command will create a virtual environment, install EEST's packages in "[editable mode](https://setuptools.pypa.io/en/latest/userguide/development_mode.html)" (source changes get reflected in the interactive shell), and start an `ipython` shell. You can then import any of the packages and experiment with them interactively.
 
-!!! example "Example: Working with `ethereum_test_forks`"
+{{< callout info "Example: Working with `ethereum_test_forks`" >}}
+See which defined forks are "ignored" by default:
 
-    See which defined forks are "ignored" by default:
-
-    ```python
-    from ethereum_test_forks import forks, get_forks
-    forks = set([fork for fork in get_forks() if fork.ignore()])
-    print(forks)
-    # -> {MuirGlacier, ArrowGlacier, GrayGlacier}
-    ```
+```python
+from ethereum_test_forks import forks, get_forks
+forks = set([fork for fork in get_forks() if fork.ignore()])
+print(forks)
+# -> {MuirGlacier, ArrowGlacier, GrayGlacier}
+```
+{{< /callout >}}
 
 ## Required `ipython` Configuration
 

docs/dev/logging.md → docs/content/main/dev_docs/logging.md

@@ -1,4 +1,7 @@
-# Logging
++++
+title = 'Logging'
+weight = 30
++++
 
 This document describes the logging system used in the Ethereum Execution Spec Tests project. Currently, logging is only supported for `consume` commands.
 

docs/dev/index.md → docs/content/main/dev_docs/main.md

@@ -1,4 +1,13 @@
-# Developer Documentation
++++
+title = 'Developer Documentation'
+date = 2025-07-09T12:42:33Z
+draft = false
+[menu]
+  [menu.main]
+    name = 'Developer Doc'
+    weight = 25
+
++++
 
 This documentation is aimed at `execution-spec-tests` developers:
 

docs/dev/precommit.md → docs/content/main/dev_docs/precommit.md

@@ -1,4 +1,7 @@
-# Enabling Pre-Commit Checks
++++
+title = 'Enabling Pre-Commit Checks'
+weight = 35
++++
 
 There's a [pre-commit](https://pre-commit.com/) config file available in the repository root (`.pre-commit-config.yaml`) that can be used to enable automatic checks upon commit - the commit will not go through if the checks don't pass.
 
@@ -8,9 +11,10 @@ To enable pre-commit, the following must be run once:
 uvx pre-commit install
 ```
 
-!!! note "Bypassing pre-commit checks"
-    Enabling of pre-commit checks is not mandatory (it cannot be enforced) and even if it is enabled, it can always be bypassed with:
+{{< callout info "Bypassing pre-commit checks" >}}
+Enabling of pre-commit checks is not mandatory (it cannot be enforced) and even if it is enabled, it can always be bypassed with:
 
-    ```console
-    git commit --no-verify
-    ```
+```console
+git commit --no-verify
+```
+{{< /callout >}}

docs/dev/test_actions_locally.md → docs/content/main/dev_docs/test_actions_locally.md

@@ -1,4 +1,7 @@
-# Running Github Actions Locally
++++
+title = 'Running Github Actions Locally'
+weight = 40
++++
 
 The Github Actions workflows can be tested locally using [nektos/act](https://github.com/nektos/act) without pushing changes to the remote. The local repository state will be used in the executed workflow.
 
@@ -27,12 +30,13 @@ The Github Actions workflows can be tested locally using [nektos/act](https://gi
 
     or use one of the [other available methods](https://nektosact.com/installation/index.html).
 
-!!! note "Updating nektos/act to the latest version via the Github CLI"
-    The `act` tool can be updated via the Github CLI:
+{{< callout info "Updating nektos/act to the latest version via the Github CLI" >}}
+The `act` tool can be updated via the Github CLI:
 
-    ```bash
-    gh extension upgrade nektos/act
-    ```
+```bash
+gh extension upgrade nektos/act
+```
+{{< /callout >}}
 
 ## Listing the Available Workflows
 

docs/filling_tests/debugging_t8n_tools.md → docs/content/main/filling_tests/debugging_t8n_tools.md

@@ -1,14 +1,16 @@
-# Debugging Transition Tools
++++
+title = 'Debugging Transition Tools'
++++
 
 There are two flags that can help debugging `t8n` tools or the execution-spec-tests framework:
 
-1. `--evm-dump-dir`: Write debug information from `t8n` tool calls to the specified directory.
+1. `--evm-dump-dir` (Default: <repo>/logs/evm): Write debug information from `t8n` tool calls to the specified directory.
 2. `--traces`: Collect traces of the execution from the transition tool.
 3. `--verify-fixtures`: Run go-ethereum's `evm blocktest` command to verify the generated test fixtures.
 
 ## EVM Dump Directory
 
-The `--evm-dump-dir` flag tells the framework to write the inputs and outputs of every call made to the `t8n` command to the specified output directory. The aim is to help debugging or simply understand how a test is interacting with the EVM. Debug output is only generated when this flag is explicitly specified.
+The `--evm-dump-dir` flag tells the framework to write the inputs and outputs of every call made to the `t8n` command to the specified output directory. The aim is to help debugging or simply understand how a test is interacting with the EVM. The default location is `logs/evm` in the project root.
 
 Each test case receives its own sub-directory under the `--evm-dump-dir` that contains these files which can be easily accessed from the HTML test report generated by `fill` (located by default in the root of the `--output` directory).
 
@@ -169,13 +171,10 @@ where the `verify_fixtures.sh` script can be used to reproduce the `evm blocktes
       --single-fixture-per-file
     ```
 
-!!! note "Execution scope of `evm blocktest`"
+{{< callout info "Execution scope of `evm blocktest`" >}}
+Note, by default, that `evm blocktest` is not executed per parametrized test case, but rather per test function. This is because each fixture JSON file contains fixtures for all the parametrized test cases for one test function. This means only one error will be reported, even if multiple fixtures fail within one fixture file.
 
-    Note, by default, that `evm blocktest` is not executed per parametrized test case, but rather per test function. This is because each fixture JSON file contains fixtures for all the parametrized test cases for one test function. This means only one error will be reported, even if multiple fixtures fail within one fixture file.
-
-    Additionally, it is only executed after all the test cases in the module have been executed[^1] and will only report the first failing test fixture in all files, even if there are multiple failing fixture files.
-
-    This means, by default, that the feedback is not as granular as for test case execution. To improve granularity, and get feedback per parametrized test case use `--single-fixture-per-file`.
+Additionally, it is only executed after all the test cases in the module have been executed and will only report the first failing test fixture in all files, even if there are multiple failing fixture files. This limitation is required to enable support of the [`pytest-xdist` plugin](https://github.com/pytest-dev/pytest-xdist) for concurrent test execution across multiple CPUs. To achieve this we use the we apply the `--dist loadscope` xdist flag in our `pytest.ini`.
 
-[^1]: <!-- markdownlint-disable MD053 (53=link-image-reference-definitions) -->
-    This limitation is required to enable support of the [`pytest-xdist` plugin](https://github.com/pytest-dev/pytest-xdist) for concurrent test execution across multiple CPUs. To achieve this we use the we apply the `--dist loadscope` xdist flag in our `pytest-fill.ini`.
+This means, by default, that the feedback is not as granular as for test case execution. To improve granularity, and get feedback per parametrized test case use `--single-fixture-per-file`.
+{{< /callout >}}

docs/filling_tests/filling_tests_command_line.md → docs/content/main/filling_tests/filling_tests_command_line.md

@@ -1,15 +1,18 @@
-# Filling Tests at a Prompt
++++
+title = 'Filling Tests at a Prompt'
++++
 
-The execution-spec-tests test framework uses the [pytest framework](https://docs.pytest.org/en/latest/) for test case collection and execution. The `fill` command is essentially an alias for `pytest`, which uses several [custom pytest plugins](../library/pytest_plugins/index.md) to run transition tools against test cases and generate JSON fixtures.
+The execution-spec-tests test framework uses the [pytest framework](https://docs.pytest.org/en/latest/) for test case collection and execution. The `fill` command is essentially an alias for `pytest`, which uses several [custom pytest plugins](../library/pytest_plugins/main.md) to run transition tools against test cases and generate JSON fixtures.
 
-!!! note "Options specific to execution-spec-tests"
-    The command-line options specific to filling tests can be listed via:
+{{< callout info "Options specific to execution-spec-tests" >}}
+The command-line options specific to filling tests can be listed via:
 
-    ```console
-    uv run fill --help
-    ```
+```console
+uv run fill --help
+```
 
-    See [Custom `fill` Command-Line Options](#custom-fill-command-line-options) for all options.
+See [Custom `fill` Command-Line Options](#custom-fill-command-line-options) for all options.
+{{< /callout >}}
 
 ## Collection - Test Exploration
 
@@ -47,8 +50,9 @@ To generate all the test fixtures defined in the `./tests/shanghai` sub-director
 uv run fill ./tests/shanghai --output="fixtures-shanghai"
 ```
 
-!!! note "Test case verification"
-    Note, that the (limited set of) test `post` conditions are tested against the output of the `evm t8n` command during test generation.
+{{< callout info "Test case verification" >}}
+Note, that the (limited set of) test `post` conditions are tested against the output of the `evm t8n` command during test generation.
+{{< /callout >}}
 
 To generate all the test fixtures in the `tests/shanghai/eip3651_warm_coinbase/test_warm_coinbase.py` module, for example, run:
 
@@ -76,17 +80,18 @@ uv run fill tests/shanghai/eip3651_warm_coinbase/test_warm_coinbase.py::test_war
 
 ## Execution for Development Forks
 
-!!! note ""
-    By default, test cases are not filled for upcoming Ethereum forks so that they can be readily filled using the `evm` tool from the latest `geth` release.
+{{< callout info "Note" >}}
+By default, test cases are not filled for upcoming Ethereum forks so that they can be readily filled using the `evm` tool from the latest `geth` release.
 
-    In order to fill test cases for an upcoming fork, ensure that the `evm` tool used supports that fork and features under test and use the `--until` or `--fork` flag.
+In order to fill test cases for an upcoming fork, ensure that the `evm` tool used supports that fork and features under test and use the `--until` or `--fork` flag.
 
-    For example, as of Q2 2023, the current fork under active development is `Cancun`:
-    ```console
-    uv run fill --until Cancun
-    ```
+For example, as of Q2 2023, the current fork under active development is `Cancun`:
+```console
+uv run fill --until Cancun
+```
+{{< /callout >}}
 
-    See: [Filling Tests for Features under Development](./filling_tests_dev_fork.md).
+See: [Filling Tests for Features under Development](./filling_tests_dev_fork.md).
 
 ## Debugging the `t8n` Command