Wasted-Audio · dromer · Feb 9, 2026 · Jan 24, 2026 · Jan 24, 2026 · Jan 26, 2026
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,29 @@
+name: Publish Docs
+on:
+  push:
+    branches:
+      - master
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material
+      - run: mkdocs gh-deploy --force
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -7,34 +7,35 @@ Please use English for all communications to include as many people as possible.
 
 ## Did you find a bug?
 
-* **Ensure the bug was not already reported** by searching on GitHub under [Issues](https://github.com/Wasted-Audio/hvcc/issues).
+- **Ensure the bug was not already reported** by searching on GitHub under [Issues](https://github.com/Wasted-Audio/hvcc/issues).
 
-* If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/Wasted-Audio/hvcc/issues/new). Be sure to include a **title and clear description**, as much relevant information as possible, and a minimal **code sample** or an **executable test case** demonstrating the expected behavior that is not occurring.
+- If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/Wasted-Audio/hvcc/issues/new). Be sure to include a **title and clear description**, as much relevant information as possible, and a minimal **code sample** or an **executable test case** demonstrating the expected behavior that is not occurring.
 
 ## Want to enhance the code?
 
 ### How to start
 
-* Create an issue to discuss your idea before you spend a lot of time into designing or coding.
-* Leave an `I like to work on this` comment on an existing issue to let the maintainer know about it.
-* Fork the repository into your personal GitHub account to get started.
-* Create a separate branch for each feature or bug-fix.
+- Create an issue to discuss your idea before you spend a lot of time into designing or coding.
+- Leave an `I like to work on this` comment on an existing issue to let the maintainer know about it.
+- Fork the repository into your personal GitHub account to get started.
+- Create a separate branch for each feature or bug-fix.
 
 ### While contributing
 
-* Make sure that existing static code analysis and tests keep working.
-  * run `TOXENV=flake8 tox` for style checking
-  * run `TOXENV=mypy tox` for type checking
-  * run `tox` for the full suite of tests or `poetry run pytest tests/` for just the test suite.
-* Write unit, integration or end-to-end tests as appropriate to your feature or bug-fix.
-* Review and update the [Changelog](CHANGELOG.md) and [Documentation](/docs/). Your changes may affect sections of these documents.
-* If your feature is large, or has a significant impact on other parts of the code, write an [Architecture Decision Record](/docs/ADRs/) describing the consideractions related to the change.
+- Make sure that existing static code analysis and tests keep working.
+  - run `TOXENV=flake8 tox` for style checking
+  - run `TOXENV=mypy tox` for type checking
+  - run `tox` for the full suite of tests or `poetry run pytest tests/` for just the test suite.
+- Write unit, integration or end-to-end tests as appropriate to your feature or bug-fix.
+- Review and update the [Changelog](CHANGELOG.md) and [Documentation](/docs/). Your changes may affect sections of these documents.
+  - You can run the documentation locally using `mkdocs serve`.
+- If your feature is large, or has a significant impact on other parts of the code, write an [Architecture Decision Record](/docs/ADRs/) describing the consideractions related to the change.
 
 ### Git best practices
 
-* This project uses [git-flow](https://danielkummer.github.io/git-flow-cheatsheet/) and [Semantic Versioning](https://semver.org/)
-* Pull requests will automatically be opened against the `develop` branch.
-* Be sure to include a textual description in both your commit(s) and in the pull request if you are implementing a new feature or changing the behavior of an existing one.
+- This project uses [git-flow](https://danielkummer.github.io/git-flow-cheatsheet/) and [Semantic Versioning](https://semver.org/)
+- Pull requests will automatically be opened against the `develop` branch.
+- Be sure to include a textual description in both your commit(s) and in the pull request if you are implementing a new feature or changing the behavior of an existing one.
 
 ## Want to create examples?
 

diff --git a/README.md b/README.md
@@ -16,47 +16,47 @@ It has since then been expanded to provide further support for many different pl
 
 ## Documentation
 
-* [Introduction](/docs/01.introduction.md)
-  * [What is heavy?](/docs/01.introduction.md#what-is-heavy)
-  * [Supported patch formats](/docs/01.introduction.md#supported-patch-formats)
-  * [Supported platforms](/docs/01.introduction.md#supported-platforms)
-  * [Supported frameworks](/docs/01.introduction.md#supported-frameworks)
-  * [Licensing](/docs/01.introduction.md#licensing)
-* [Getting Started](/docs/02.getting_started.md)
-* [Generators](/docs/03.generators.md)
-* [MIDI](/docs/04.midi.md)
-* [C API](/docs/05.c.md)
-* [C++ API](/docs/06.cpp.md)
-* [Heavy Lang Info](/docs/07.heavy_lang.md)
-* [Heavy IR Info](/docs/08.heavy_ir_lang.md)
-* [Heavy GUI IR Info](/docs/11.heavy_gui_ir.md)
-* [Supported vanilla objects](/docs/09.supported_vanilla_objects.md)
-* [Unsupported vanilla objects](/docs/10.unsupported_vanilla_objects.md)
+- [Introduction](docs/getting-started/index.md)
+  - [What is heavy?](docs/getting-started/index.md#what-is-heavy)
+  - [Supported patch formats](docs/getting-started/index.md#supported-patch-formats)
+  - [Supported platforms](docs/getting-started/index.md#supported-platforms)
+  - [Supported frameworks](docs/getting-started/index.md#supported-frameworks)
+  - [Licensing](docs/getting-started/index.md#licensing)
+- [Getting Started](docs/getting-started/patching.md)
+- [Generators](docs/generators/index.md)
+- [MIDI](docs/reference/midi.md)
+- [C API](docs/reference/c.md)
+- [C++ API](docs/reference/cpp.md)
+- [Heavy Lang Info](docs/reference/ir/heavy_lang.md)
+- [Heavy IR Info](docs/reference/ir/heavy_ir.md)
+- [Heavy GUI IR Info](docs/reference/ir/heavy_gui_ir.md)
+- [Supported vanilla objects](docs/reference/objects/supported.md)
+- [Unsupported vanilla objects](docs/reference/objects/unsupported.md)
 
 ## Integrations
 
 hvcc has been integrated into several projects and services. This allows to easily compile patches without having to install hvcc manually.
 
-* [plugdata](https://plugdata.org/) - Modern interface for Pure Data. Includes a full cross-platform toolchain and targets Daisy, DPF and PD Externals.
-* [mod-cloud-builder](https://github.com/moddevices/mod-cloud-builder) - Online service for building LV2 plugins for the MOD platform.
-* [OWL Patch Library](https://www.rebeltech.org/patch-library) - Online service for building OWL plugins (uses an old fork).
+- [plugdata](https://plugdata.org/) - Modern interface for Pure Data. Includes a full cross-platform toolchain and targets Daisy, DPF and PD Externals.
+- [mod-cloud-builder](https://github.com/moddevices/mod-cloud-builder) - Online service for building LV2 plugins for the MOD platform.
+- [OWL Patch Library](https://www.rebeltech.org/patch-library) - Online service for building OWL plugins (uses an old fork).
 
 ## Requirements
 
 Python 3.9 up to 3.14
 
-* `jinja2` (for generator templating)
-* `pydantic` (for data types)
-* `pydantic-extra-types` (for data types)
-* `arpeggio` (for `expr~` translation)
+- `jinja2` (for generator templating)
+- `pydantic` (for data types)
+- `pydantic-extra-types` (for data types)
+- `arpeggio` (for `expr~` translation)
 
 For tests:
 
-* `tox` (python install)
-* `numpy/scipy` (dev dependencies)
-* `midifile` (git submodule)
-* `tinywav` (git submodule)
-* `clang/clang++` (system install)
+- `tox` (python install)
+- `numpy/scipy` (dev dependencies)
+- `midifile` (git submodule)
+- `tinywav` (git submodule)
+- `clang/clang++` (system install)
 
 ## Installation
 
@@ -88,9 +88,9 @@ hvcc ~/myProject/_main.pd
 
 This command will generate the following directories:
 
-* `~/myProject/hv` heavylang representation of the input pd patch(es)
-* `~/myProject/ir` heavyir representation of the heavylang patch
-* `~/myProject/c` final generated C/C++ source files (this is what you would use in your project)
+- `~/myProject/hv` heavylang representation of the input pd patch(es)
+- `~/myProject/ir` heavyir representation of the heavylang patch
+- `~/myProject/c` final generated C/C++ source files (this is what you would use in your project)
 
 ### `-o` Select output directory
 
@@ -132,7 +132,7 @@ It is also possible to pass a list of generators:
 hvcc ~/myProject/_main.pd -o ~/Desktop/somewhere/else/ -n mySynth -g unity wwise js
 ```
 
-A list of available generator options can be found [here](/docs/03.generators.md)
+A list of available generator options can be found [here](docs/generators/index.md)
 
 ### `-p` Search Paths
 
@@ -172,13 +172,13 @@ The Heavy community aims to be safe and inclusive, please read our [Code of Cond
 
 There are several places where heavy/hvcc conversation is happening:
 
-* [Discord](https://discord.gg/fmxJveg)
-* [IRC](https://web.libera.chat/#hvcc)
-* A number of forums:
-  * [Bela](https://forum.bela.io/?q=hvcc)
-  * [Rebel Technology](https://community.rebeltech.org/tags/puredata)
-  * [Daisy](https://forum.electro-smith.com/c/integrations/pure-data/32)
-  * [MOD](https://forum.moddevices.com/c/developers/pure-data/56)
+- [Discord](https://discord.gg/fmxJveg)
+- [IRC](https://web.libera.chat/#hvcc)
+- A number of forums:
+  - [Bela](https://forum.bela.io/?q=hvcc)
+  - [Rebel Technology](https://community.rebeltech.org/tags/puredata)
+  - [Daisy](https://forum.electro-smith.com/c/integrations/pure-data/32)
+  - [MOD](https://forum.moddevices.com/c/developers/pure-data/56)
 
 Or you can use the [discussions](https://github.com/Wasted-Audio/hvcc/discussions) tab of this repository
 

diff --git a/docs/03.generators.md b/docs/03.generators.md